akanjs 3.0.0-beta.9 → 3.0.1

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

@@ -0,0 +1,275 @@
+
+
+import { EXTERNAL_OPENS_PER_SECOND } from "../../core/src/contract.ts";
+import type { AppInfo, CallScope, FileRef } from "../../core/src/index.ts";
+import type { QuitReason, Veto } from "./lifecycle.ts";
+
+export type { QuitReason, Veto } from "./lifecycle.ts";
+export { createPageVeto, type PageVeto } from "./page-veto.ts";
+
+/**
+ * Which pages an event goes to. Default: every page that listens. `{ window }`: only that
+ * window's page (window events). "focused": only the most recently focused window that listens
+ * (something to handle once, like a deep link).
+ */
+export type EmitTarget = { window: number } | "focused";
+
+export interface DesktopContext {
+  app: AppInfo;
+  /**
+   * A debug build (boot.json `dev`: `--debug`, and every dev build, whose pages come from a dev server the shell did not
+   * start). It has the release app's id, so what it keeps apart goes in folders of its own.
+   */
+  readonly dev: boolean;
+  /**
+   * The window whose page made this call (SH-6; 1 = the window the app opened). Only in method
+   * calls; undefined in setup and event sources.
+   */
+  readonly window?: number;
+  /**
+   * What the app's capabilities allow this method call (PL-11): enforce it with
+   * `scopePermits(ctx.scope, { field: value }, pathFields, urlFields)` from @akanjs/native/core. Undefined when no
+   * matching grant carries scopes (only the plugin's own rules apply). Only in method calls.
+   */
+  readonly scope?: CallScope;
+  /**
+   * Fires when the page gives up on this call (its AbortSignal: v1.1 `cancel`) or the page is gone.
+   * The page has its answer by then (CANCELLED or TIMEOUT); stop the work and release what it
+   * holds. Only in method calls.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * The calling page's document (one page load; bridge v1.1 `doc`), for what must not outlive it:
+   * `ctx.document.own(() => db.close())`. Only in method calls.
+   */
+  readonly document?: DocumentScope;
+  /** Per-app data folder, e.g. ~/Library/Application Support/<app id>. Created on first access. */
+  readonly appDataDir: string;
+  /**
+   * For what is large and belongs to this PC (caches, downloads, databases): %LOCALAPPDATA%\<app id> on Windows,
+   * where appDataDir roams with the user; appDataDir on macOS and Linux. Created on first access.
+   */
+  readonly appLocalDataDir: string;
+  /**
+   * The executables the app carries (desktop.bin, akanjs `bin`), or null. The host puts the folder first on
+   * process.env.PATH, which node:child_process and `Bun.spawn(cmd, { env: process.env })` use; a Bun.spawn or
+   * Bun.which without `env` reads the environment the app started with, so name a file here or pass the env.
+   */
+  readonly binDir: string | null;
+  /**
+   * The server the app carries (desktop.server), or null. `ready` settles once per session: true when the server
+   * first answered ready, false when it could not start or gave up before that; `state` and `onState` follow it after.
+   */
+  readonly server: DesktopServerStatus | null;
+  /** Pushes an event of this plugin to the pages that listen. Returns the windows reached. */
+  emit(event: string, data?: unknown, target?: EmitTarget): number[];
+  /** Serves a local file at /__akan_native/file/<id> for the rest of the session (PL-7). */
+  registerFile(path: string, mime: string): FileRef;
+  /**
+   * Runs a native shell command on the main thread, e.g. shell("window.setTitle", { title }).
+   * Window ops act on `args.window`; without it, on the calling window in a method call, else on
+   * the most recently focused window.
+   */
+  shell(op: string, args?: Record<string, unknown>): Promise<unknown>;
+  /** Native shell events ("window", "opened", "pageLoad", …). Returns an unsubscribe function. */
+  onNativeEvent(type: string, listener: (event: NativeEvent) => void): () => void;
+  /** The app's deep link schemes (deepLinks.schemes in akan-native.config.ts), lowercase. */
+  readonly deepLinkSchemes: readonly string[];
+  /**
+   * What may be handed to the OS (L0): http, https, mailto, tel and security.shell.externalSchemes.
+   * Plugins that open URLs outside the app check them and call `externalOpenAllowed()` first.
+   */
+  readonly externalSchemes: readonly string[];
+  /**
+   * Hands a launch's arguments to the "opened" listeners when they are a deep link (D6). Windows
+   * and Linux start a new process for a link; single-instance passes that process's arguments
+   * here. Anything but a single URL of one of the app's schemes is ignored (deeplinks.ts).
+   */
+  openLinks(args: readonly string[]): void;
+  /** Ends the app with an exit code, after the onQuit hooks. Does not ask onBeforeQuit. */
+  quit(code?: number): void;
+  /**
+   * Cleanup before the app quits, however it quits (Cmd+Q, window close, app.exit(), logout).
+   * All hooks run together and the app waits for them at most 2 s. Returns an unregister function.
+   */
+  onQuit(fn: () => void | Promise<void>): () => void;
+  /**
+   * Runs when any window's page document ends (reload, navigation, window destroyed, renderer
+   * gone), after its calls, subscriptions and owned resources were closed. For a plugin's own
+   * per-window tables. Returns an unregister function.
+   */
+  onDocumentEnd(fn: (doc: DocumentInfo) => void): () => void;
+  /** Veto for quit requests (Cmd+Q, Dock, AppleScript, logout, last window closed): return false to keep running. */
+  onBeforeQuit(fn: Veto<{ reason: QuitReason }>): () => void;
+  /** Veto for a window's close button and Cmd+W: return false to keep that window open. */
+  onCloseRequested(fn: Veto<{ window: number }>): () => void;
+  /**
+   * Closes a window without asking (default: the calling window in a method call, else window 1).
+   * Another window is left: it is destroyed. It was the last one: the app quits, or hides it when
+   * desktop.quitOnLastWindowClosed is false.
+   */
+  closeWindow(window?: number): void;
+  /**
+   * Launch phase: only while setup runs, before the window exists. The host waits for every
+   * plugin's setup (async allowed, at most 3 s each) before it creates the window. setWindow after
+   * that is ignored with a warning.
+   */
+  readonly launch: {
+    /** Creates the window at these bounds (logical points) instead of the configured size (window-state). */
+    setWindow(bounds: LaunchWindow): void;
+    /**
+     * Ends the app before a window is created; onQuit hooks do not run (single-instance). A setup that ran past its
+     * time quits the app instead, since its window exists by then.
+     */
+    exit(code?: number): void;
+  };
+}
+
+/**
+ * "starting" until the server answers ready (again after a crash before that), "up" while it answers, "restarting"
+ * after a crash once it had been up, "gaveUp" when it is not started again this session, "stopped" as the app quits.
+ */
+export type DesktopServerState = "starting" | "up" | "restarting" | "gaveUp" | "stopped";
+
+export interface DesktopServerStatus {
+  readonly ready: Promise<boolean>;
+  readonly state: DesktopServerState;
+  /** Every later change of `state`. Returns an unsubscribe function. */
+  onState(listener: (state: DesktopServerState) => void): () => void;
+}
+
+/** Which page load ended. `id` is "" for a page that sends no document id (v1 callers, tests). */
+export interface DocumentInfo {
+  window: number;
+  id: string;
+}
+
+/**
+ * One page load of a window (architecture §3.7 Document scope). Module state of a desktop plugin is
+ * App scope: keep per-page state here, or keyed by window and cleared in onDocumentEnd.
+ */
+export interface DocumentScope extends DocumentInfo {
+  /** True once the page is gone. */
+  readonly ended: boolean;
+  /**
+   * Ties a resource to this page: `dispose` runs when it ends (the last owned first), or right away
+   * if it already has (a call that finished after its page left). Returns a function that forgets
+   * the resource without disposing it (it was closed on request).
+   */
+  own(dispose: () => unknown): () => void;
+}
+
+/** Initial window bounds from the launch phase. The shell drops a position that is on no display. */
+export interface LaunchWindow {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  maximized?: boolean;
+  /** Borderless fullscreen from the first frame, on the display x and y are on (else the primary one). */
+  fullscreen?: boolean;
+  /** No taskbar button (Windows, Linux; macOS has none). */
+  skipTaskbar?: boolean;
+}
+
+/** What the launch phase decided; sent to the main thread with "ready". */
+export interface Launch {
+  window: LaunchWindow;
+  exit?: number;
+  /** PUBLIC_* values for the page known only at launch (the carried server's URL), under AKAN_NATIVE_PUBLIC_*. */
+  env?: Record<string, string>;
+}
+
+export interface NativeEvent {
+  type: string;
+  [key: string]: unknown;
+}
+
+type MethodImpl<F> = F extends (args: infer A) => Promise<infer R>
+  ? (args: A, ctx: DesktopContext) => R | Promise<R>
+  : F extends () => Promise<infer R>
+    ? (args: undefined, ctx: DesktopContext) => R | Promise<R>
+    : never;
+
+export interface DesktopPlugin<Api = any, Events = any> {
+  id: string;
+  /**
+   * Runs once when the plugin host starts, before the window exists and before any page call
+   * (e.g. to catch launch events). May be async: the window waits for it (ctx.launch).
+   */
+  setup?(ctx: DesktopContext): void | Promise<void>;
+  /**
+   * "gate": this setup runs before every other one, one gate plugin after the other, and when one
+   * decides the launch exits (ctx.launch.exit, e.g. single-instance handing over to the running
+   * instance), the other setups do not run at all.
+   */
+  launchPhase?: "gate";
+  /** A window's page document ended (see DesktopContext.onDocumentEnd). */
+  onDocumentEnd?(doc: DocumentInfo, ctx: DesktopContext): void;
+  methods: { [K in keyof Api]?: MethodImpl<Api[K]> };
+  /**
+   * Event sources, started for the first $listen from any page and stopped after the last
+   * $unlisten. `emit` reaches the pages that listen (see EmitTarget) and returns their windows
+   * (typed `| void` so tests can pass a plain function).
+   */
+  events?: {
+    [E in keyof Events]?: (
+      emit: (data: Events[E], target?: EmitTarget) => number[] | void,
+      ctx: DesktopContext,
+    ) => () => void;
+  };
+}
+
+/**
+ * Plugins' external opens (opener, browser, auth-session, …) happen at most
+ * EXTERNAL_OPENS_PER_SECOND times a second, whichever plugin asks (L0; the shell limits the page's
+ * links the same way). false: refuse the open (NOT_ALLOWED).
+ */
+let lastExternalOpen = -Infinity;
+const linkClaimers = new Set<(url: string) => boolean>();
+
+/**
+ * A plugin that answers some links itself (auth-session's sign-in callback, R10) takes them before
+ * the app plugin turns them into urlOpen. `claim` says whether a URL is its own; returns the removal.
+ */
+export function claimLinks(claim: (url: string) => boolean): () => void {
+  linkClaimers.add(claim);
+  return () => linkClaimers.delete(claim);
+}
+
+/** Whether a plugin took this link (the app plugin then does not deliver it). */
+export function linkClaimed(url: string): boolean {
+  for (const claim of linkClaimers) {
+    try {
+      if (claim(url)) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+
+let limitOpens = true;
+/** The shell's own counter (akan_native_external_open_allowed), which the page's links use too. */
+let shellLimiter: (() => boolean) | null = null;
+export function externalOpenAllowed(now = performance.now()): boolean {
+  if (!limitOpens) return true;
+  if (shellLimiter) return shellLimiter();
+  if (now - lastExternalOpen < 1000 / EXTERNAL_OPENS_PER_SECOND) return false;
+  lastExternalOpen = now;
+  return true;
+}
+
+/** The plugin host: plugins' opens share the shell's counter with the page's links. */
+export function useShellOpenLimit(limiter: () => boolean): void {
+  shellLimiter = limiter;
+}
+
+/** Unit tests only: plugins' tests open many URLs in a row. */
+export function limitExternalOpens(enabled: boolean): void {
+  limitOpens = enabled;
+  lastExternalOpen = -Infinity;
+}
+
+export function defineDesktopPlugin<Api, Events = {}>(plugin: DesktopPlugin<Api, Events>): DesktopPlugin<Api, Events> {
+  return plugin;
+}

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

@@ -0,0 +1,236 @@
+
+
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname } from "node:path";
+
+export interface RelaunchOptions {
+  /** How long the helper waits after this process exited before it starts the app. */
+  delayMs?: number;
+  /**
+   * Windows, a swap: while the helper moves the folders, a RunOnce value named `name` runs `script` (written here) at
+   * the next logon, which puts back what a shutdown or a killed helper left half moved and starts the app. The helper
+   * removes the value once the moves are done or undone.
+   */
+  recover?: { script: string; name: string };
+}
+
+const RUN_ONCE = "HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\RunOnce";
+
+/** A PowerShell single-quoted literal. */
+const quoted = (value: string) => `'${value.replaceAll("'", "''")}'`;
+
+/**
+ * The recovery `recover.script` holds: when `exe` is missing, every move whose source is gone and whose target is
+ * there goes back, newest first, and the app starts. An app that is there was never half moved: it is left alone.
+ */
+export function recoveryScript(exe: string, moves: [string, string][]): string {
+  return `$ErrorActionPreference = 'SilentlyContinue'
+$exe = ${quoted(exe)}
+if (Test-Path -LiteralPath $exe) { exit }
+$moves = ${quoted(JSON.stringify(moves))} | ConvertFrom-Json
+[array]::Reverse($moves)
+foreach ($m in $moves) { if (-not (Test-Path -LiteralPath $m[0]) -and (Test-Path -LiteralPath $m[1])) { Move-Item -LiteralPath $m[1] -Destination $m[0] } }
+if (Test-Path -LiteralPath $exe) { Start-Process -WorkingDirectory $env:TEMP -FilePath $exe }
+`;
+}
+
+/**
+ * The RunOnce command for a recovery script, or null past the 260 characters Windows runs from there. The script is
+ * read as text: an execution policy that refuses .ps1 files does not apply to it, as it does not to -EncodedCommand.
+ */
+export function recoveryCommand(script: string): string | null {
+  const command = `powershell.exe -NoProfile -NonInteractive -WindowStyle Hidden -Command "iex ([IO.File]::ReadAllText(${quoted(script)}))"`;
+  return command.length <= 260 ? command : null;
+}
+
+let started: Promise<void> | null = null;
+
+/**
+ * Once this process has exited: renames `moves` in order and starts `exe` with this environment. macOS and
+ * Linux rename a running app's folder right away, so only the start waits; Windows refuses that, so a helper
+ * does the renames too (and on a failed rename puts back what it moved, so there is always an app to start).
+ * Only the first call of a process starts a helper; later ones answer the same promise.
+ */
+export function relaunchAfterExit(
+  exe: string,
+  moves: [string, string][] = [],
+  { delayMs = 0, recover }: RelaunchOptions = {},
+): Promise<void> {
+  if (started) return started;
+  try {
+    const helper = startHelper(exe, moves, Math.max(0, Math.round(delayMs)), recover);
+    started = helper;
+    return helper;
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+
+function startHelper(
+  exe: string,
+  moves: [string, string][],
+  delayMs: number,
+  recover: RelaunchOptions["recover"],
+): Promise<void> {
+
+  const { AKAN_NATIVE_QUIT_ON_STDIN: _cli, ...inherited } = process.env;
+  const delay = (delayMs / 1000).toFixed(3);
+  if (process.platform !== "win32") {
+    const done: [string, string][] = [];
+    try {
+      for (const [from, to] of moves) {
+        renameSync(from, to);
+        done.unshift([from, to]);
+      }
+    } catch (error) {
+      for (const [from, to] of done) {
+        try {
+          renameSync(to, from);
+        } catch (undo) {
+          console.error(`[akan-native] cannot put ${from} back`, undo);
+        }
+      }
+      throw error;
+    }
+    
+    const child = spawn(
+      "/bin/sh",
+      [
+        "-c",
+        'while kill -0 "$AKAN_NATIVE_PARENT" 2>/dev/null && [ "$(ps -o stat= -p "$AKAN_NATIVE_PARENT" 2>/dev/null | cut -c1)" != Z ]; do sleep 0.2; done; sleep "$AKAN_NATIVE_DELAY"; exec "$AKAN_NATIVE_EXE"',
+      ],
+      {
+        detached: true,
+        stdio: "inherit",
+        env: {
+          ...inherited,
+          AKAN_NATIVE_PARENT: String(process.pid),
+          AKAN_NATIVE_EXE: exe,
+          AKAN_NATIVE_DELAY: delay,
+        },
+      },
+    );
+    child.once("error", (error) => console.error("[akan-native] cannot start the relaunch helper", error));
+    child.unref();
+    return Promise.resolve();
+  }
+
+  const script = `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+Wait-Process -Id $env:AKAN_NATIVE_PARENT -ErrorAction SilentlyContinue
+$moves = $env:AKAN_NATIVE_MOVES | ConvertFrom-Json
+$runOnce = '${RUN_ONCE}'
+if ($env:AKAN_NATIVE_RECOVER) {
+  try {
+    if (-not (Test-Path $runOnce)) { New-Item -Path $runOnce -Force | Out-Null }
+    Set-ItemProperty -Path $runOnce -Name $env:AKAN_NATIVE_RECOVER_NAME -Value $env:AKAN_NATIVE_RECOVER
+  } catch {}
+}
+$done = @()
+try {
+  foreach ($m in $moves) {
+    for ($i = 0; ; $i++) { try { Move-Item -LiteralPath $m[0] -Destination $m[1]; break } catch { if ($i -ge 40) { throw }; Start-Sleep -Milliseconds 250 } }
+    $done = ,$m + $done
+  }
+} catch {
+  foreach ($m in $done) { try { Move-Item -LiteralPath $m[1] -Destination $m[0] } catch {} }
+}
+if ($env:AKAN_NATIVE_RECOVER) { Remove-ItemProperty -Path $runOnce -Name $env:AKAN_NATIVE_RECOVER_NAME -ErrorAction SilentlyContinue }
+Start-Sleep -Milliseconds ([int]$env:AKAN_NATIVE_DELAY_MS)
+Start-Process -NoNewWindow -WorkingDirectory $env:AKAN_NATIVE_CWD -FilePath $env:AKAN_NATIVE_EXE
+`;
+  let recovery: Record<string, string> = {};
+  const command = recover && moves.length > 0 ? recoveryCommand(recover.script) : null;
+  if (recover && command) {
+    try {
+      mkdirSync(dirname(recover.script), { recursive: true });
+      writeFileSync(recover.script, `\uFEFF${recoveryScript(exe, moves)}`);
+      recovery = { AKAN_NATIVE_RECOVER: command, AKAN_NATIVE_RECOVER_NAME: recover.name };
+    } catch (error) {
+      console.warn("[akan-native] cannot write the swap's recovery script", error);
+    }
+  } else if (recover && moves.length > 0)
+    console.warn(`[akan-native] ${recover.script} is too long a path for RunOnce`);
+
+  const encoded = Buffer.from(script, "utf16le").toString("base64");
+
+  const cwd = tmpdir();
+  const env = {
+    ...inherited,
+    AKAN_NATIVE_PARENT: String(process.pid),
+    AKAN_NATIVE_EXE: exe,
+    AKAN_NATIVE_MOVES: JSON.stringify(moves),
+    AKAN_NATIVE_DELAY_MS: String(delayMs),
+    AKAN_NATIVE_CWD: cwd,
+    ...recovery,
+  };
+  const args = [
+    "/d",
+    "/c",
+    "start",
+    "/b",
+    "powershell.exe",
+    "-NoProfile",
+    "-NonInteractive",
+    "-WindowStyle",
+    "Hidden",
+    "-EncodedCommand",
+    encoded,
+  ];
+  let child: ReturnType<typeof spawn>;
+  try {
+    child = spawn("cmd.exe", args, { cwd, stdio: "inherit", windowsHide: true, env });
+  } catch {
+    child = spawn("cmd.exe", args, { cwd, stdio: "ignore", windowsHide: true, env }); 
+  }
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = setTimeout(done, 2_500); 
+    child.once("exit", done);
+    child.once("error", (error) => {
+      console.error("[akan-native] cannot start the relaunch helper", error);
+      done();
+    });
+  });
+}
+
+/** Relaunches after the browser process ended, in a row: each one's app ran less than RELAUNCH_HEALTHY. */
+export const RELAUNCH_LIMIT = 10;
+export const RELAUNCH_HEALTHY = 60_000;
+
+interface RelaunchRecord {
+  streak: number;
+  /** When the last relaunched app was due to start (epoch ms). */
+  startsAt: number;
+}
+
+/**
+ * desktop.recovery "reload" after the webview's browser process ended: how long the relaunched app waits, or null
+ * once RELAUNCH_LIMIT relaunches in a row did not help. The first relaunch is immediate, then 1 s doubling to a
+ * minute (lib.rs recovery_wait); an app that ran for RELAUNCH_HEALTHY starts the count again. `file` keeps the
+ * count across the processes.
+ */
+export function nextRelaunchDelay(file: string, now = Date.now()): number | null {
+  let last: RelaunchRecord | null = null;
+  try {
+    const raw = JSON.parse(readFileSync(file, "utf8")) as Partial<RelaunchRecord>;
+    if (typeof raw.streak === "number" && typeof raw.startsAt === "number")
+      last = { streak: raw.streak, startsAt: raw.startsAt };
+  } catch {}
+  const streak = last && now - last.startsAt < RELAUNCH_HEALTHY ? last.streak + 1 : 0;
+  if (streak >= RELAUNCH_LIMIT) return null;
+  const delay = streak === 0 ? 0 : Math.min(1000 * 2 ** Math.min(streak - 1, 6), 60_000);
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ streak, startsAt: now + delay } satisfies RelaunchRecord));
+  } catch (error) {
+    console.warn("[akan-native] cannot record the relaunch", error);
+  }
+  return delay;
+}