akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/packages/desktop/src/ffi.ts

@@ -0,0 +1,76 @@
+
+
+import { dlopen } from "bun:ffi";
+import { dirname, join } from "node:path";
+
+export interface DesktopPaths {
+  /** The native library: libakan_native_desktop.dylib, akan_native_desktop.dll or libakan_native_desktop.so */
+  lib: string;
+  /** boot.json, env.runtime.json, shell.json, app/ (platforms/desktop.ts in the CLI) */
+  resources: string;
+  appDir: string;
+}
+
+/**
+ * Paths relative to the executable, as the CLI lays them out (packages/cli/src/platforms/*.ts):
+ *   macOS    <App>.app/Contents/MacOS/<exe>, Frameworks/libakan_native_desktop.dylib, Resources/
+ *   Windows  <App>\<exe>.exe, akan_native_desktop.dll, resources\
+ *   Linux    <app>/<exe>, lib/libakan_native_desktop.so, resources/
+ * process.execPath is absolute even when the app is started with `open` (cwd = /) or through a
+ * symlink. Nothing in the environment overrides them: the app would load whatever library a
+ * variable (or a .env file next to it, before the build turned autoloading off) names.
+ */
+export function resolvePaths(platform: NodeJS.Platform = process.platform, execPath = process.execPath): DesktopPaths {
+  const exeDir = dirname(execPath);
+  const [lib, resources] =
+    platform === "darwin"
+      ? [join(exeDir, "..", "Frameworks", "libakan_native_desktop.dylib"), join(exeDir, "..", "Resources")]
+      : platform === "win32"
+        ? [join(exeDir, "akan_native_desktop.dll"), join(exeDir, "resources")]
+        : [join(exeDir, "lib", "libakan_native_desktop.so"), join(exeDir, "resources")];
+  return { lib, resources, appDir: join(resources, "app") };
+}
+
+/** The C ABI major version this code speaks (lib.rs ABI >> 16). */
+export const ABI_MAJOR = 0;
+
+export const SYMBOLS = {
+  akan_native_abi: { args: [], returns: "u32" },
+  akan_native_init: { args: ["u8"], returns: "i32" },
+  akan_native_last_error: { args: ["ptr", "u64"], returns: "u64" },
+  akan_native_run: { args: ["ptr"], returns: "i32" },
+  akan_native_set_wake: { args: ["ptr"], returns: "void" },
+  akan_native_poll: { args: ["ptr", "u32"], returns: "u32" },
+  akan_native_respond: { args: ["u64", "u16", "ptr", "ptr", "u32"], returns: "void" },
+  akan_native_emit: { args: ["u32", "ptr"], returns: "void" },
+  akan_native_register_file: { args: ["ptr", "ptr", "ptr"], returns: "void" },
+  akan_native_unregister_file: { args: ["ptr"], returns: "u8" },
+  akan_native_quit: { args: ["i32"], returns: "void" },
+  akan_native_quit_cancel: { args: [], returns: "void" },
+  akan_native_external_open_allowed: { args: [], returns: "u8" },
+  akan_native_shell: { args: ["u64", "ptr"], returns: "void" },
+} as const;
+
+export function openNative(libPath: string) {
+  return dlopen(libPath, SYMBOLS);
+}
+
+/** The native library's last error (akan_native_last_error), or "". */
+export function lastError(lib: NativeLib): string {
+  const size = Number(lib.symbols.akan_native_last_error(null, 0));
+  if (size === 0) return "";
+  const buf = new Uint8Array(size);
+  lib.symbols.akan_native_last_error(buf, size);
+  return new TextDecoder().decode(buf);
+}
+
+export type NativeLib = ReturnType<typeof openNative>;
+
+const encoder = new TextEncoder();
+/** NUL-terminated UTF-8. Native code copies it during the call, so it may be collected afterwards. */
+export const cstr = (text: string) => encoder.encode(`${text}\0`);
+
+/** Message kinds in akan_native_poll frames: [u8 kind][u64 reqId LE][u32 webviewId LE][body]. */
+export const FRAME_IPC = 1;
+export const FRAME_EVENT = 2;
+export const FRAME_HEADER = 13;

package/vendor/@akanjs/native/packages/desktop/src/host.ts

@@ -0,0 +1,355 @@
+
+
+import { JSCallback } from "bun:ffi";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync, watch } from "node:fs";
+import { extname, join, sep } from "node:path";
+import { ID_FILE_REF } from "../../core/src/contract.ts";
+import type { AppInfo, ErrorCode } from "../../core/src/index.ts";
+import { AkanNativeError, aclCheck, loadAcl } from "../../core/src/index.ts";
+import { CONSOLE_PLUGIN, ERROR_CODES, errorResponse, HOST_PLUGIN } from "../../core/src/protocol.ts";
+import { linkArguments, registerDeepLinks } from "./deeplinks.ts";
+import { createDispatcher } from "./dispatcher.ts";
+import { cstr, FRAME_EVENT, FRAME_HEADER, FRAME_IPC, openNative, resolvePaths } from "./ffi.ts";
+import { createLifecycle } from "./lifecycle.ts";
+import { appDataDir, reservedDirs } from "./paths.ts";
+import { type DesktopPlugin, useShellOpenLimit } from "./plugin.ts";
+
+declare const self: Worker;
+
+/** A drain handles at most this many frames, or runs this long, before it yields (see drain). */
+export const DRAIN_FRAMES = 256;
+export const DRAIN_MS = 4;
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+const JSON_TYPE = cstr("application/json");
+
+interface NativeEvent {
+  type: string;
+  event?: string;
+  url?: string;
+  id?: number;
+  ok?: boolean;
+  result?: unknown;
+  error?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * A failed shell op. Ops may name the error code first ("UNSUPPORTED: no tray on this desktop");
+ * other messages are about the arguments.
+ */
+export function shellError(message: string): AkanNativeError {
+  const m = /^([A-Z_]+): ([\s\S]*)$/.exec(message);
+  return m && ERROR_CODES.includes(m[1] as ErrorCode)
+    ? new AkanNativeError(m[1] as ErrorCode, m[2]!)
+    : new AkanNativeError("INVALID_ARGS", message);
+}
+
+export function startHost(plugins: DesktopPlugin[]): void {
+  const paths = resolvePaths();
+  const lib = openNative(paths.lib);
+  const native = lib.symbols;
+  
+  useShellOpenLimit(() => native.akan_native_external_open_allowed() === 1);
+  const boot = JSON.parse(readFileSync(join(paths.resources, "boot.json"), "utf8")) as {
+    app: AppInfo;
+    dev?: boolean;
+    acl?: unknown;
+    plugins?: Record<string, unknown>;
+  };
+  
+  const { acl, problem: aclProblem } = loadAcl(boot);
+  if (aclProblem)
+    console.error(
+      `[akan-native] boot.json: the capabilities cannot be read (${aclProblem}); every plugin call is denied`,
+    );
+
+  const emitJs = (window: number, js: string) => native.akan_native_emit(window, cstr(js));
+
+  const windows = new Set<number>([1]);
+  let focusOrder: number[] = [1];
+  const trackWindows = (event: NativeEvent) => {
+    const window = typeof event.window === "number" ? event.window : 1;
+    if (event.type !== "window") return;
+    if (event.event === "created") windows.add(window);
+    else if (event.event === "destroyed") {
+      windows.delete(window);
+      focusOrder = focusOrder.filter((w) => w !== window);
+    } else if (event.event === "focused" && event.value === true)
+      focusOrder = [window, ...focusOrder.filter((w) => w !== window)];
+  };
+
+  /** Web content processes that ended (the self-test's $host.gone). */
+  let gone = 0;
+  /** $host.hang calls that were cancelled (the self-test's cancel check). */
+  let cancels = 0;
+  /** FileRefs served now (K13). */
+  const fileIds = new Set<string>();
+
+  let shellSeq = 0;
+  const shellPending = new Map<number, { resolve(v: unknown): void; reject(e: unknown): void }>();
+  const nativeListeners = new Map<string, Set<(event: NativeEvent) => void>>();
+  const shell = (op: string, args: Record<string, unknown> = {}) => {
+    const id = ++shellSeq;
+    return new Promise<unknown>((resolve, reject) => {
+      shellPending.set(id, { resolve, reject });
+      native.akan_native_shell(BigInt(id), cstr(JSON.stringify({ ...args, op })));
+    });
+  };
+
+  const shellConfig = JSON.parse(readFileSync(join(paths.resources, "shell.json"), "utf8")) as {
+    quitOnLastWindowClosed?: boolean;
+    deepLinks?: string[];
+    externalSchemes?: string[];
+  };
+  const deepLinkSchemes = (shellConfig.deepLinks ?? []).map((s) => s.toLowerCase());
+  
+  const openLinks = (args: readonly string[]) => {
+    const urls = linkArguments(args, deepLinkSchemes);
+    if (urls.length) onEvent({ type: "opened", urls });
+  };
+  const lifecycle = createLifecycle({
+    quitOnLastWindowClosed: shellConfig.quitOnLastWindowClosed !== false,
+    exit(code) {
+      dispatcher.reset();
+      native.akan_native_quit(code);
+    },
+    cancelSessionEnd: () => native.akan_native_quit_cancel(),
+    hideWindow: (window) => shell("window.hide", { window }),
+    destroyWindow: (window) => shell("window.destroy", { window }),
+    windows: async () => ((await shell("window.list")) as { id: number }[]).map((w) => w.id),
+  });
+
+  const reserved = reservedDirs(boot.app.id);
+  const dispatcher = createDispatcher(
+    plugins,
+    {
+      app: boot.app,
+      appDataDir: appDataDir(boot.app.id),
+      emit(window, message) {
+        emitJs(window, `window.__AKAN_NATIVE__&&window.__AKAN_NATIVE__.receive(${JSON.stringify(message)})`);
+      },
+      builtins: {
+        
+        [CONSOLE_PLUGIN](req, window) {
+          const line = `[page${window === 1 ? "" : ` ${window}`} ${req.method}] ${(req.args as { message?: string } | undefined)?.message ?? ""}`;
+          (req.method === "error" || req.method === "warn" ? console.error : console.info)(line);
+        },
+        
+        async [HOST_PLUGIN](req, window, signal) {
+          if (req.method === "print") {
+            if (!aclCheck(acl, "core", "print", window).allowed) {
+              throw new AkanNativeError(
+                "NOT_ALLOWED",
+                "window.print() is not allowed by the app's capabilities (core:deny-print)",
+              );
+            }
+            await shell("webview.print", { window });
+            return;
+          }
+          if (req.method === "crash" && boot.dev) {
+            
+            setTimeout(
+              () =>
+                void shell("webview.crashForTest", { window }).catch((e: unknown) =>
+                  console.error("[akan-native] crash for test:", e),
+                ),
+              100,
+            );
+            return;
+          }
+          if (req.method === "gone" && boot.dev) return { count: gone };
+          
+          if (req.method === "burst" && boot.dev) {
+            const count = Number((req.args as { count?: number } | undefined)?.count ?? 0);
+            for (let n = 0; n < count; n++) dispatcher.emitTo(window, HOST_PLUGIN, "tick", { n });
+            return { sent: count };
+          }
+          
+          if (req.method === "stats" && boot.dev) return await shell("debug.stats");
+          
+          if (req.method === "hang" && boot.dev)
+            return new Promise((resolve) =>
+              signal.addEventListener("abort", () => resolve((cancels++, undefined)), { once: true }),
+            );
+          
+          if (req.method === "info" && boot.dev) {
+            let listeners = 0;
+            for (const set of nativeListeners.values()) listeners += set.size;
+            return {
+              windows: windows.size,
+              cancels,
+              stats: { ...dispatcher.stats(), files: fileIds.size, nativeListeners: listeners },
+            };
+          }
+          if (req.method === "echo" && boot.dev) {
+            
+            setTimeout(() => dispatcher.emitTo(window, HOST_PLUGIN, "echo", req.args), 0);
+            return req.args;
+          }
+          throw new AkanNativeError("NOT_FOUND", `unknown host method ${req.method}`);
+        },
+      },
+      focusOrder: () => focusOrder.filter((w) => windows.has(w)),
+      registerFile(path, mime) {
+        
+        const real = realpathSync(path);
+        if (!statSync(real).isFile()) throw new AkanNativeError("INVALID_ARGS", `${path} is not a file`);
+        const inside = (dir: string, p: string) => p === dir || p.startsWith(dir + sep);
+        for (const { root, except } of reserved) {
+          const r = existsSync(root) ? realpathSync(root) : root;
+          if (inside(r, real) && !except.some((e) => inside(existsSync(e) ? realpathSync(e) : e, real))) {
+            throw new AkanNativeError("NOT_ALLOWED", `${path} is in the app's own storage and cannot be served`);
+          }
+        }
+        
+        const ext = [...extname(path).slice(1)]
+          .filter((c) => ID_FILE_REF.extChars.includes(c))
+          .join("")
+          .slice(0, ID_FILE_REF.extMax);
+        const id = randomBytes(12).toString("base64url") + (ext ? `.${ext}` : "");
+        
+        native.akan_native_register_file(cstr(id), cstr(real), cstr(mime));
+        fileIds.add(id);
+        return { url: `/__akan_native/file/${id}`, mime, size: statSync(real).size };
+      },
+      releaseFile(url) {
+        const id = /^(?:app:\/\/localhost)?\/__akan_native\/file\/([^/?#]+)$/.exec(url)?.[1];
+        if (id === undefined || native.akan_native_unregister_file(cstr(id)) !== 1) return false;
+        fileIds.delete(id);
+        return true;
+      },
+      shell,
+      deepLinkSchemes,
+      externalSchemes: shellConfig.externalSchemes ?? [],
+      openLinks,
+      onNativeEvent(type, listener) {
+        let set = nativeListeners.get(type);
+        if (!set) {
+          set = new Set();
+          nativeListeners.set(type, set);
+        }
+        set.add(listener);
+        return () => set!.delete(listener);
+      },
+      lifecycle,
+    },
+    { acl, declarations: boot.plugins },
+  );
+
+  const respond = (reqId: bigint, status: number, body: unknown) => {
+    const bytes = encoder.encode(JSON.stringify(body));
+    native.akan_native_respond(reqId, status, JSON_TYPE, bytes, bytes.length);
+  };
+
+  const onIpc = async (reqId: bigint, body: Uint8Array, window: number) => {
+    respond(reqId, 200, await dispatcher.handle(decoder.decode(body), window));
+  };
+
+  const onEvent = (event: NativeEvent) => {
+    if (event.type === "shellReply" && typeof event.id === "number") {
+      const pending = shellPending.get(event.id);
+      shellPending.delete(event.id);
+      if (event.ok) pending?.resolve(event.result);
+      else pending?.reject(shellError(String(event.error)));
+      return;
+    }
+    trackWindows(event);
+    
+    for (const listener of [...(nativeListeners.get(event.type) ?? [])]) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error(`[akan-native] native event listener for ${event.type} failed`, error);
+      }
+    }
+    const window = typeof event.window === "number" ? event.window : 1;
+    if (event.type === "pageLoad" && event.event === "started") dispatcher.reset(window);
+    else if (event.type === "webview" && event.event === "processTerminated") {
+      gone++;
+      console.error(`[akan-native] window ${window}: the page's process ended (${String(event.reason)})`);
+      dispatcher.reset(window);
+    } else if (event.type === "window" && event.event === "destroyed") dispatcher.reset(window);
+    else if (event.type === "window" && event.event === "closeRequested") void lifecycle.closeRequested(window);
+    else if (event.type === "quitRequested")
+      void lifecycle.requestQuit(event.reason === "session" ? "session" : "user");
+    else if (event.type === "signal") void lifecycle.quit(0);
+    else if (event.type === "external") console.info(`[akan-native] opened in the browser: ${event.url}`);
+  };
+
+  let buffer = new Uint8Array(64 * 1024);
+
+  let continuation: ReturnType<typeof setTimeout> | null = null;
+  const drain = () => {
+    const started = performance.now();
+    for (let frames = 0; ; frames++) {
+      if (frames >= DRAIN_FRAMES || performance.now() - started > DRAIN_MS) {
+        continuation ??= setTimeout(() => {
+          continuation = null;
+          drain();
+        }, 0);
+        return;
+      }
+      const size = native.akan_native_poll(buffer, buffer.length);
+      if (size === 0) return;
+      if (size > buffer.length) {
+        buffer = new Uint8Array(Math.max(size, buffer.length * 2));
+        continue;
+      }
+      const view = new DataView(buffer.buffer, buffer.byteOffset, size);
+      const kind = view.getUint8(0);
+      const reqId = view.getBigUint64(1, true);
+      const webview = view.getUint32(9, true);
+      const body = buffer.slice(FRAME_HEADER, size); 
+      try {
+        if (kind === FRAME_IPC) {
+          onIpc(reqId, body, webview || 1).catch((error) => {
+            console.error("[akan-native] bridge call failed", error);
+            respond(reqId, 500, errorResponse(0, "INTERNAL", String(error)));
+          });
+        } else if (kind === FRAME_EVENT) {
+          onEvent(JSON.parse(decoder.decode(body)));
+        }
+      } catch (error) {
+        
+        console.error("[akan-native] native message failed", error);
+        if (kind === FRAME_IPC) respond(reqId, 500, errorResponse(0, "INTERNAL", String(error)));
+      }
+    }
+  };
+
+  const wake = new JSCallback(drain, { args: [], returns: "void", threadsafe: true });
+  native.akan_native_set_wake(wake.ptr);
+
+  process.on("exit", () => native.akan_native_set_wake(null)); 
+  process.on("uncaughtException", (error) =>
+    console.error("[akan-native] uncaught exception in the plugin host", error),
+  );
+  process.on("unhandledRejection", (error) =>
+    console.error("[akan-native] unhandled rejection in the plugin host", error),
+  );
+  
+  if (boot.dev && process.env.AKAN_NATIVE_DEV_WATCH === "1") {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    watch(paths.appDir, { recursive: true }, () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        for (const window of windows) emitJs(window, "location.reload()");
+      }, 150);
+    });
+  }
+  
+  setInterval(() => {}, 2 ** 31 - 1);
+  
+  void dispatcher.launched.then((launch) => {
+    self.postMessage({ type: "ready", ...launch });
+    if (typeof launch.exit === "number") return;
+    
+    openLinks(process.argv.slice(2));
+    registerDeepLinks(boot.app, deepLinkSchemes).catch((error) =>
+      console.warn("[akan-native] cannot register the deep link schemes", error),
+    );
+  });
+}

package/vendor/@akanjs/native/packages/desktop/src/lifecycle.ts

@@ -0,0 +1,142 @@
+
+
+export type QuitReason = "user" | "session" | "lastWindowClosed";
+
+/** Return false (or resolve to false) to keep the app running / the window open. */
+export type Veto<E> = (event: E) => boolean | void | Promise<boolean | void>;
+
+export interface LifecycleOptions {
+  quitOnLastWindowClosed: boolean;
+  /** Ends the process (akan_native_quit). */
+  exit(code: number): void;
+  /** The app stays after a logout asked it to quit (akan_native_quit_cancel). */
+  cancelSessionEnd(): void;
+  /** Hides the last window instead of quitting (quitOnLastWindowClosed: false). */
+  hideWindow(window: number): Promise<unknown>;
+  /** Destroys a window that is not the last one. */
+  destroyWindow?(window: number): Promise<unknown>;
+  /** The windows that exist, hidden ones included. Default: only the one being closed. */
+  windows?(): Promise<number[]>;
+  /** How long quit() waits for the onQuit hooks, all together. Default QUIT_HOOK_TIMEOUT. */
+  quitHookTimeout?: number;
+}
+
+export interface Lifecycle {
+  onQuit(fn: () => void | Promise<void>): () => void;
+  onBeforeQuit(fn: Veto<{ reason: QuitReason }>): () => void;
+  onCloseRequested(fn: Veto<{ window: number }>): () => void;
+  /** A window's close button or Cmd+W: asks the close vetoes, then closeWindow(window). */
+  closeRequested(window?: number): Promise<void>;
+  /**
+   * Closes a window without asking: destroys it while another window exists, else a quit
+   * request, or hide (quitOnLastWindowClosed: false).
+   */
+  closeWindow(window?: number): Promise<void>;
+  /** Asks the quit vetoes, then quits. Resolves true when the app quits. */
+  requestQuit(reason: QuitReason): Promise<boolean>;
+  /** Quits without asking: onQuit hooks, then exit. */
+  quit(code?: number): Promise<void>;
+}
+
+export const QUIT_HOOK_TIMEOUT = 2000;
+
+async function allow<E>(vetoes: Set<Veto<E>>, event: E, what: string): Promise<boolean> {
+  for (const veto of [...vetoes]) {
+    try {
+      if ((await veto(event)) === false) return false;
+    } catch (error) {
+      
+      console.error(`[akan-native] ${what} handler failed`, error);
+    }
+  }
+  return true;
+}
+
+function register<T>(set: Set<T>, value: T): () => void {
+  set.add(value);
+  return () => void set.delete(value);
+}
+
+export function createLifecycle(options: LifecycleOptions): Lifecycle {
+  const quitHooks = new Set<() => void | Promise<void>>();
+  const quitVetoes = new Set<Veto<{ reason: QuitReason }>>();
+  const closeVetoes = new Set<Veto<{ window: number }>>();
+  let quitting: Promise<void> | null = null;
+  let deciding: Promise<boolean> | null = null;
+  const closing = new Map<number, Promise<void>>();
+  let sessionWaiting = false;
+
+  const quit = (code = 0): Promise<void> => {
+    quitting ??= (async () => {
+      const hooks = [...quitHooks].map(async (hook) => {
+        try {
+          await hook();
+        } catch (error) {
+          console.error("[akan-native] quit hook failed", error);
+        }
+      });
+      const timeout = options.quitHookTimeout ?? QUIT_HOOK_TIMEOUT;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const late = new Promise<"late">((resolve) => (timer = setTimeout(() => resolve("late"), timeout)));
+      if ((await Promise.race([Promise.all(hooks), late])) === "late")
+        console.error(`[akan-native] quit hooks did not finish within ${timeout} ms`);
+      clearTimeout(timer);
+      sessionWaiting = false;
+      options.exit(code);
+    })();
+    return quitting;
+  };
+
+  const requestQuit = (reason: QuitReason): Promise<boolean> => {
+    if (reason === "session") sessionWaiting = true;
+    if (quitting) return Promise.resolve(true);
+    
+    deciding ??= (async () => {
+      const ok = await allow(quitVetoes, { reason }, "beforeQuit");
+      deciding = null;
+      if (ok) {
+        void quit(0);
+        return true;
+      }
+      if (sessionWaiting) {
+        sessionWaiting = false;
+        options.cancelSessionEnd();
+      }
+      return false;
+    })();
+    return deciding;
+  };
+
+  const closeWindow = async (window = 1): Promise<void> => {
+    const windows = options.windows ? await options.windows() : [window];
+    
+    if (windows.some((w) => w !== window)) await options.destroyWindow?.(window);
+    else if (options.quitOnLastWindowClosed) await requestQuit("lastWindowClosed");
+    else await options.hideWindow(window);
+  };
+
+  return {
+    onQuit: (fn) => register(quitHooks, fn),
+    onBeforeQuit: (fn) => register(quitVetoes, fn),
+    onCloseRequested: (fn) => register(closeVetoes, fn),
+    closeRequested(window = 1) {
+      if (quitting) return Promise.resolve();
+      
+      let pending = closing.get(window);
+      if (!pending) {
+        pending = (async () => {
+          try {
+            if (await allow(closeVetoes, { window }, "closeRequested")) await closeWindow(window);
+          } finally {
+            closing.delete(window);
+          }
+        })();
+        closing.set(window, pending);
+      }
+      return pending;
+    },
+    closeWindow,
+    requestQuit,
+    quit,
+  };
+}