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

package/vendor/@akanjs/native/plugins/single-instance/src/desktop.ts

@@ -0,0 +1,63 @@
+
+
+import { RetainedEvents } from "../../../packages/core/src/kernel.ts";
+import { type DesktopContext, defineDesktopPlugin, type EmitTarget } from "../../../packages/desktop/src/plugin.ts";
+import type { SecondInstance, SingleInstanceEvents } from "./index.ts";
+import { claim, socketPath } from "./socket.ts";
+
+/** Shows, un-minimizes (keeping it maximized if it was) and focuses the window. */
+async function bringToFront(ctx: DesktopContext): Promise<void> {
+  await ctx.shell("window.show");
+  await ctx.shell("window.unminimize");
+  await ctx.shell("window.focus");
+}
+
+export function createDesktopSingleInstance(
+  options: { path?: (appId: string) => string; args?: () => string[]; cwd?: () => string } = {},
+) {
+  /** Kept for the first listener (plugins.md C2, kernel RetainedEvents), like deep links before the page is ready. */
+  const messages = new RetainedEvents<SecondInstance>();
+  let listens = 0;
+
+  const received = (ctx: DesktopContext, message: SecondInstance) => {
+    bringToFront(ctx).catch((error) => console.error("[akan-native] single-instance: cannot focus the window", error));
+    
+    ctx.openLinks(message.args);
+    messages.emit(message, true);
+  };
+
+  return defineDesktopPlugin<{}, SingleInstanceEvents>({
+    id: "single-instance",
+    
+    launchPhase: "gate",
+    async setup(ctx) {
+      const path = (options.path ?? socketPath)(ctx.app.id);
+      const message = { args: options.args?.() ?? process.argv.slice(2), cwd: options.cwd?.() ?? process.cwd() };
+      const result = await claim(path, message, (m) => received(ctx, m));
+      if (result.kind === "forwarded") {
+        console.info(
+          "[akan-native] single-instance: another instance is already running; handed over to it and exiting",
+        );
+        ctx.launch.exit(0);
+      } else if (result.kind === "primary") {
+        ctx.onQuit(() => result.close());
+      } else {
+        console.warn(`[akan-native] single-instance: running without the lock (${result.error.message})`);
+      }
+    },
+    methods: {},
+    events: {
+      secondInstance(emit) {
+        
+        const key = String(++listens);
+        messages.listen(
+          key,
+          (m) => ((emit as (m: SecondInstance, target?: EmitTarget) => number[] | void)(m, "focused")?.length ?? 1) > 0,
+        );
+        return () => messages.unlisten(key);
+      },
+    },
+  });
+}
+
+export default createDesktopSingleInstance();

package/vendor/@akanjs/native/plugins/single-instance/src/index.ts

@@ -0,0 +1,32 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+
+/**
+ * One running instance per app on the desktop. Adding the plugin to akan-native.config.ts turns it on:
+ * a second launch hands its arguments to the running instance and exits before it creates a
+ * window; the running instance brings its window to the front and emits `secondInstance`.
+ *
+ * - macOS: launching from Finder, the Dock or `open` already reuses the running app; this
+ *   covers direct launches of the executable and `open -n`. Deep links reach the running app
+ *   through the `app` plugin's `urlOpen` either way.
+ * - Windows and Linux (later): deep links arrive as arguments, so this plugin is how they reach
+ *   the running instance (plugins.md §5).
+ * - Web, iOS and Android: UNSUPPORTED (the OS keeps one instance).
+ *
+ * Events that arrive before the page listens are kept (up to 16) and delivered to the first
+ * listener, like deep links (plugins.md C2).
+ */
+export interface SecondInstance {
+  /** The second launch's arguments, without the executable. */
+  args: string[];
+  /** Its working directory, for resolving relative paths in `args`. */
+  cwd: string;
+}
+
+export interface SingleInstanceEvents {
+  secondInstance: SecondInstance;
+}
+
+export const singleInstance = definePlugin<{}, SingleInstanceEvents>("single-instance", {
+  methods: [],
+  events: ["secondInstance"],
+});

package/vendor/@akanjs/native/plugins/single-instance/src/socket.ts

@@ -0,0 +1,248 @@
+
+
+import { dlopen, FFIType } from "bun:ffi";
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, constants, openSync, rmSync } from "node:fs";
+import { connect, createServer, type Server, type Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { SecondInstance } from "./index.ts";
+
+const FORMAT = 1;
+const ACK = "ok\n";
+/** One message is a few KiB of arguments; anything larger is not from us. */
+const MAX_MESSAGE = 256 * 1024;
+
+/**
+ * sun_path is 104 bytes on macOS, so the name is a short hash, not the app id. Windows pipe names
+ * are one namespace for the whole PC, so the user is part of the hash there; other users cannot
+ * write to a pipe they did not create (its default security), so they cannot pose as it either.
+ */
+export function socketPath(
+  appId: string,
+  env: Record<string, string | undefined> = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (platform === "win32") {
+    const hash = createHash("sha256")
+      .update(`${env.USERDOMAIN ?? ""}\\${env.USERNAME ?? ""}\0${appId}`)
+      .digest("hex")
+      .slice(0, 16);
+    return `\\\\.\\pipe\\akan-native-${hash}`;
+  }
+  const dir = env.XDG_RUNTIME_DIR || env.TMPDIR || tmpdir();
+  const hash = createHash("sha256").update(appId).digest("hex").slice(0, 16);
+  return join(dir, `akan-native-${hash}.sock`);
+}
+
+/** A named pipe disappears with its server: there is no file to protect or clean up. */
+const isPipe = (path: string) => path.startsWith("\\\\.\\pipe\\");
+
+export function encodeMessage(message: SecondInstance): string {
+  return `${JSON.stringify({ format: FORMAT, args: message.args, cwd: message.cwd })}\n`;
+}
+
+export function decodeMessage(line: string): SecondInstance | null {
+  try {
+    const v = JSON.parse(line);
+    if (
+      v?.format !== FORMAT ||
+      !Array.isArray(v.args) ||
+      !v.args.every((a: unknown) => typeof a === "string") ||
+      typeof v.cwd !== "string"
+    ) {
+      return null;
+    }
+    return { args: v.args, cwd: v.cwd };
+  } catch {
+    return null;
+  }
+}
+
+export type Claim =
+  | { kind: "primary"; close(): void }
+  /** Another instance runs: it got the message (or did not answer in time; this launch exits either way). */
+  | { kind: "forwarded" }
+  /** The lock file cannot be made (e.g. the folder is not writable): run without the lock. */
+  | { kind: "failed"; error: Error };
+
+type Lock = { kind: "held"; fd: number } | { kind: "busy" } | { kind: "unavailable"; error: Error };
+
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+/** node:fs has no O_CLOEXEC constant, and Bun's open does not add it (checked with fcntl F_GETFD). */
+const O_CLOEXEC = process.platform === "darwin" ? 0x1000000 : 0o2000000;
+let libc: { symbols: { flock(fd: number, operation: number): number } } | null = null;
+
+/**
+ * flock(LOCK_EX | LOCK_NB) on `path`, opened with node:fs (open(2) is variadic, which bun:ffi
+ * cannot call portably); flock itself comes from the C library. The descriptor stays open for the
+ * process: closing it would release the lock. It is close-on-exec: a process the app starts with
+ * fork/exec (native code, xdg-open, a relaunch) would otherwise keep the lock after the app quit,
+ * and every later launch would hand its message to nobody and exit.
+ */
+export function lockFile(path: string): Lock {
+  let fd: number;
+  try {
+    fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | O_CLOEXEC, 0o600);
+  } catch (error) {
+    return { kind: "unavailable", error: error as Error };
+  }
+  try {
+    libc ??= dlopen(process.platform === "darwin" ? "/usr/lib/libSystem.B.dylib" : "libc.so.6", {
+      flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+    });
+  } catch (error) {
+    closeSync(fd);
+    return { kind: "unavailable", error: error as Error };
+  }
+  if (libc.symbols.flock(fd, LOCK_EX | LOCK_NB) === 0) return { kind: "held", fd };
+  closeSync(fd);
+  return { kind: "busy" };
+}
+
+const errno = (error: unknown) => (error as NodeJS.ErrnoException)?.code;
+
+function listen(path: string, onMessage: (m: SecondInstance) => void): Promise<Server> {
+  return new Promise((resolve, reject) => {
+    const server = createServer((socket) => serve(socket, onMessage));
+    server.once("error", reject);
+    server.listen(path, () => {
+      server.off("error", reject);
+      server.on("error", (error) => console.error("[akan-native] single-instance:", error));
+      resolve(server);
+    });
+  });
+}
+
+function serve(socket: Socket, onMessage: (m: SecondInstance) => void): void {
+  let buffered = "";
+  socket.setEncoding("utf8");
+  socket.setTimeout(2000, () => socket.destroy());
+  socket.on("error", () => {});
+  socket.on("data", (chunk: string) => {
+    buffered += chunk;
+    if (buffered.length > MAX_MESSAGE) return void socket.destroy();
+    const nl = buffered.indexOf("\n");
+    if (nl < 0) return;
+    const message = decodeMessage(buffered.slice(0, nl));
+    socket.end(message ? ACK : "");
+    if (message) onMessage(message);
+  });
+}
+
+/** Sends the message; resolves true once the running instance acknowledged it. */
+function send(path: string, message: SecondInstance, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    const socket = connect(path);
+    let reply = "";
+    let connected = false;
+    const timer = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, timeoutMs);
+    socket.setEncoding("utf8");
+    socket.once("connect", () => {
+      connected = true;
+      socket.write(encodeMessage(message));
+    });
+    socket.on("data", (chunk: string) => (reply += chunk));
+    socket.once("close", () => {
+      clearTimeout(timer);
+      resolve(reply === ACK);
+    });
+    socket.once("error", (error) => {
+      clearTimeout(timer);
+      socket.destroy();
+      if (connected) resolve(false);
+      else reject(error);
+    });
+  });
+}
+
+/**
+ * Becomes the running instance, or hands `message` to the one that is.
+ * A running instance that does not acknowledge within `timeoutMs` (hung) still counts:
+ * starting a second window next to it is what the plugin exists to prevent.
+ */
+export async function claim(
+  path: string,
+  message: SecondInstance,
+  onMessage: (m: SecondInstance) => void,
+  timeoutMs = 1500,
+): Promise<Claim> {
+  if (!isPipe(path)) return claimLocked(path, message, onMessage, timeoutMs);
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const server = await listen(path, onMessage);
+      try {
+        if (!isPipe(path)) chmodSync(path, 0o600); 
+      } catch {}
+      return {
+        kind: "primary",
+        close() {
+          server.close();
+          if (!isPipe(path)) rmSync(path, { force: true });
+        },
+      };
+    } catch (error) {
+      if (errno(error) !== "EADDRINUSE") return { kind: "failed", error: error as Error };
+    }
+    try {
+      const heard = await send(path, message, timeoutMs);
+      if (!heard) console.warn("[akan-native] single-instance: the running instance did not answer; exiting anyway");
+      return { kind: "forwarded" };
+    } catch (error) {
+      const code = errno(error);
+
+      if ((code === "ECONNREFUSED" || code === "ENOTSOCK") && !isPipe(path)) rmSync(path, { force: true });
+      else if (code !== "ENOENT") return { kind: "failed", error: error as Error };
+    }
+  }
+  return { kind: "failed", error: new Error(`could not claim ${path}`) };
+}
+
+/** macOS and Linux: whoever holds the lock file runs; the socket only carries messages. */
+async function claimLocked(
+  path: string,
+  message: SecondInstance,
+  onMessage: (m: SecondInstance) => void,
+  timeoutMs: number,
+): Promise<Claim> {
+  const lock = lockFile(`${path.replace(/\.sock$/, "")}.lock`);
+  if (lock.kind === "unavailable") return { kind: "failed", error: lock.error };
+  if (lock.kind === "held") {
+    rmSync(path, { force: true }); 
+    try {
+      const server = await listen(path, onMessage);
+      try {
+        chmodSync(path, 0o600); 
+      } catch {}
+      return {
+        kind: "primary",
+        close() {
+          server.close();
+          rmSync(path, { force: true });
+          closeSync(lock.fd); 
+        },
+      };
+    } catch (error) {
+      
+      console.warn("[akan-native] single-instance: holding the lock, but cannot listen for other launches:", error);
+      return { kind: "primary", close: () => closeSync(lock.fd) };
+    }
+  }
+  
+  const deadline = Date.now() + Math.max(timeoutMs, 3000);
+  while (Date.now() < deadline) {
+    try {
+      const heard = await send(path, message, timeoutMs);
+      if (!heard) console.warn("[akan-native] single-instance: the running instance did not answer; exiting anyway");
+      return { kind: "forwarded" };
+    } catch {
+      await Bun.sleep(100);
+    }
+  }
+  console.warn("[akan-native] single-instance: another instance holds the lock but cannot be reached; exiting");
+  return { kind: "forwarded" };
+}

package/vendor/@akanjs/native/plugins/splash-screen/android/SplashScreenPlugin.kt

@@ -0,0 +1,19 @@
+package com.akanjs.plugins.splashscreen
+
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * Lets the system splash screen go (SH-6). The shell keeps it up with a pre-draw listener
+ * (AkanNativeActivity.holdSplash) and also releases it after the first page load when splash.autoHide is on.
+ * Arguments arrive decoded and checked by the generated SplashScreenPluginSpec (PL-10).
+ */
+class SplashScreenPlugin(private val context: AkanNativePluginContext) : SplashScreenPluginSpec {
+    override fun hide(args: SplashScreenHideArgs, reply: AkanNativeVoidReply) {
+        val fade = args.fadeOutDuration ?: 200.0
+        if (fade < 0 || fade > 10_000) return reply.reject(AkanNativeErrorCode.INVALID_ARGS, "fadeOutDuration must be between 0 and 10000 ms")
+        context.hideSplash(fade.toLong())
+        reply.resolve()
+    }
+}

package/vendor/@akanjs/native/plugins/splash-screen/ios/SplashScreenPlugin.swift

@@ -0,0 +1,20 @@
+import UIKit
+
+/// Hides the shell's launch screen cover (SH-6). The cover itself belongs to the shell
+/// (AkanNativeViewController), which also hides it after the first page load when splash.autoHide is on.
+/// Arguments arrive decoded and checked by the generated SplashScreenPluginSpec (PL-10).
+final class SplashScreenPlugin: SplashScreenPluginSpec {
+    static let id = "splash-screen"
+    private let context: AkanNativePluginContext
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+    }
+
+    func hide(_ args: SplashScreenHideArgs, _ reply: AkanNativeReply<Void>) {
+        let fade = args.fadeOutDuration ?? 200
+        guard fade >= 0, fade <= 10_000 else { return reply.reject(.invalidArgs, "fadeOutDuration must be between 0 and 10000 ms") }
+        context.hideSplash(fadeOutDuration: fade / 1000)
+        reply.resolve()
+    }
+}

package/vendor/@akanjs/native/plugins/splash-screen/native-plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "splash-screen",
+  "apiVersion": 1,
+  "methods": ["hide"],
+  "events": [],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "web",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "SplashScreenPlugin"
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.splashscreen.SplashScreenPlugin"
+  }
+}

package/vendor/@akanjs/native/plugins/splash-screen/src/index.ts

@@ -0,0 +1,24 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+import { web } from "./web.ts";
+
+/**
+ * The launch screen (SH-6, plugins.md S2). The picture comes from `splash` in akan-native.config.ts;
+ * the shell shows it from launch until the first page load (`splash.autoHide`, the default) or
+ * until the app calls hide(), and at the latest until `splash.timeout`.
+ * iOS: the launch screen, then a matching cover over the WebView. Android: the system splash
+ * screen, kept up until hide. Web and desktop have no splash (desktop windows appear after the
+ * first page load instead), so hide() resolves right away there.
+ */
+export interface SplashScreenApi {
+  /**
+   * Hides the splash, fading out over `fadeOutDuration` ms (default 200). Resolves at once, also
+   * when the splash is already gone, so it is safe to call whenever the UI is ready. With
+   * `splash.autoHide: false`, call it once the first screen has rendered.
+   */
+  hide(options?: { fadeOutDuration?: number }): Promise<void>;
+}
+
+export const splashScreen = definePlugin<SplashScreenApi>("splash-screen", {
+  methods: ["hide"],
+  web,
+});

package/vendor/@akanjs/native/plugins/splash-screen/src/web.ts

@@ -0,0 +1,17 @@
+import { AkanNativeError, defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { SplashScreenApi } from "./index.ts";
+
+/** Browsers and the desktop WebView have no splash to hide. Arguments are still checked. */
+export const web = defineWebPlugin<SplashScreenApi>({
+  methods: {
+    async hide(options) {
+      checkFade(options?.fadeOutDuration);
+    },
+  },
+});
+
+export function checkFade(value: unknown): void {
+  if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 10_000)) {
+    throw new AkanNativeError("INVALID_ARGS", "fadeOutDuration must be a number of milliseconds between 0 and 10000");
+  }
+}

package/vendor/@akanjs/native/plugins/sqlite/android/SqlStatements.kt

@@ -0,0 +1,121 @@
+package com.akanjs.plugins.sqlite
+
+/**
+ * How many statements a SQL text holds, finding their ends the way sqlite3_complete() does
+ * (sqlite/src/complete.c): a CREATE [TEMP] TRIGGER statement ends only at "END ;", every other ";"
+ * outside quotes, [identifiers] and comments ends a statement. Only whitespace, comments and ";"
+ * is 0. The same code as src/common.ts countStatements (desktop), kept free of Android classes.
+ *
+ * Needed because Android compiles only the first statement of a text and drops the rest without
+ * a word (SQLiteDatabase.execSQL: "Multiple statements separated by semicolons are not
+ * supported", SQLiteDatabase.java:2147-2148 in the android-36.1 sources).
+ */
+object SqlStatements {
+    private const val SEMI = 0
+    private const val WS = 1
+    private const val OTHER = 2
+    private const val EXPLAIN = 3
+    private const val CREATE = 4
+    private const val TEMP = 5
+    private const val TRIGGER = 6
+    private const val END = 7
+
+    private val TRANS = arrayOf(
+        intArrayOf(1, 0, 2, 3, 4, 2, 2, 2), // 0 INVALID
+        intArrayOf(1, 1, 2, 3, 4, 2, 2, 2), // 1 START
+        intArrayOf(1, 2, 2, 2, 2, 2, 2, 2), // 2 NORMAL
+        intArrayOf(1, 3, 3, 2, 4, 2, 2, 2), // 3 EXPLAIN
+        intArrayOf(1, 4, 2, 2, 2, 4, 5, 2), // 4 CREATE
+        intArrayOf(6, 5, 5, 5, 5, 5, 5, 5), // 5 TRIGGER
+        intArrayOf(6, 6, 5, 5, 5, 5, 5, 7), // 6 SEMI
+        intArrayOf(1, 7, 5, 5, 5, 5, 5, 5), // 7 END
+    )
+
+    /** SQLite's IdChar(): letters, digits, "_", "$" and every non-ASCII character. */
+    private fun isIdChar(c: Char) = c in '0'..'9' || c in 'A'..'Z' || c in 'a'..'z' || c == '_' || c == '$' || c.code >= 0x80
+
+    private fun keyword(word: String) = when (word.lowercase()) {
+        "create" -> CREATE
+        "temp", "temporary" -> TEMP
+        "trigger" -> TRIGGER
+        "end" -> END
+        "explain" -> EXPLAIN
+        else -> OTHER
+    }
+
+    fun count(sql: String): Int {
+        var state = 0
+        var count = 0
+        val n = sql.length
+        var i = 0
+        while (i < n) {
+            val c = sql[i]
+            var token = OTHER
+            when {
+                c == ';' -> token = SEMI
+                c == ' ' || c == '\r' || c == '\t' || c == '\n' || c == '\u000c' -> token = WS
+                c == '/' && i + 1 < n && sql[i + 1] == '*' -> {
+                    val close = sql.indexOf("*/", i + 2)
+                    i = if (close < 0) n else close + 1
+                    token = WS
+                }
+                c == '-' && i + 1 < n && sql[i + 1] == '-' -> {
+                    val eol = sql.indexOf('\n', i + 2)
+                    i = if (eol < 0) n else eol
+                    token = WS
+                }
+                c == '[' || c == '`' || c == '"' || c == '\'' -> {
+                    val close = sql.indexOf(if (c == '[') ']' else c, i + 1)
+                    i = if (close < 0) n else close
+                }
+                isIdChar(c) -> {
+                    var j = i + 1
+                    while (j < n && isIdChar(sql[j])) j++
+                    token = keyword(sql.substring(i, j))
+                    i = j - 1
+                }
+            }
+            val next = TRANS[state][token]
+            if (token == SEMI && next == 1 && state > 1) count++
+            state = next
+            i++
+        }
+        return if (state > 1) count + 1 else count
+    }
+
+    /** The bare words of [sql] (keywords and unquoted names), lowercase, skipping quotes and comments. */
+    private fun words(sql: String): List<String> {
+        val out = ArrayList<String>()
+        val n = sql.length
+        var i = 0
+        while (i < n) {
+            val c = sql[i]
+            when {
+                c == '/' && i + 1 < n && sql[i + 1] == '*' -> sql.indexOf("*/", i + 2).let { i = if (it < 0) n else it + 1 }
+                c == '-' && i + 1 < n && sql[i + 1] == '-' -> sql.indexOf('\n', i + 2).let { i = if (it < 0) n else it }
+                c == '[' || c == '`' || c == '"' || c == '\'' -> sql.indexOf(if (c == '[') ']' else c, i + 1).let { i = if (it < 0) n else it }
+                isIdChar(c) -> {
+                    var j = i + 1
+                    while (j < n && isIdChar(sql[j])) j++
+                    out.add(sql.substring(i, j).lowercase())
+                    i = j - 1
+                }
+            }
+            i++
+        }
+        return out
+    }
+
+    /**
+     * Why [sql] is refused, or null: ATTACH opens any SQLite file the app can reach and VACUUM INTO
+     * writes one anywhere, past the filesystem plugin's scopes (src/common.ts refusedStatement).
+     */
+    fun refused(sql: String): String? {
+        val w = words(sql)
+        var i = 0
+        if (w.getOrNull(i) == "explain") i += if (w.getOrNull(i + 1) == "query" && w.getOrNull(i + 2) == "plan") 3 else 1
+        if (w.getOrNull(i) == "attach") return "ATTACH is not allowed: open every database with open()"
+        if (w.getOrNull(i) == "vacuum" && w.drop(i + 1).contains("into")) return "VACUUM INTO is not allowed: it writes a file outside the database"
+        return null
+    }
+}