@onmark/cli 0.1.3

package/packages/launcher/dist/src/browser.js

@@ -0,0 +1,280 @@
+// Verified browser installation owns the desktop capture environment cache.
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, mkdir, mkdtemp, readdir, rename, rm, rmdir, stat, utimes, writeFile, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { Cache, InstalledBrowser, install, } from "@puppeteer/browsers";
+import { BROWSER_BUILD, desktopTarget, } from "./release.js";
+const INSTALL_LOCK_TIMINGS = {
+    heartbeatMilliseconds: 10_000,
+    pollMilliseconds: 200,
+    staleMilliseconds: 60_000,
+    waitMilliseconds: 3 * 60_000,
+};
+const INSTALL_LOCK_OWNER_PREFIX = ".owner-";
+const INSTALL_STAGING_PREFIX = ".browser-install-";
+export class BrowserInstallError extends Error {
+    constructor(message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "BrowserInstallError";
+    }
+}
+// ── Installation pipeline
+export async function ensureBrowser(options, installBrowser = install) {
+    const target = desktopTarget(options.host);
+    await mkdir(options.cacheDirectory, { recursive: true });
+    return withInstallLock(options.cacheDirectory, async (lease) => {
+        const admittedCache = join(options.cacheDirectory, BROWSER_BUILD, target.sha256);
+        await mkdir(admittedCache, { recursive: true });
+        const installed = installedBrowser(admittedCache, target.browser, target.browserPlatform);
+        if (await isExecutable(installed.executablePath, options.host.platform)) {
+            return installed.executablePath;
+        }
+        await verifyInstallLease(lease);
+        await removeAbandonedStaging(admittedCache);
+        await removeIncompleteInstall(installed);
+        return installVerifiedBrowser(lease, {
+            cacheDirectory: admittedCache,
+            hostPlatform: options.host.platform,
+            installBrowser,
+            target,
+        });
+    });
+}
+async function installVerifiedBrowser(lease, installation) {
+    const staging = await mkdtemp(join(installation.cacheDirectory, INSTALL_STAGING_PREFIX));
+    return withObservedCleanup(() => publishVerifiedBrowser(lease, installation, staging), () => rm(staging, { force: true, recursive: true }), "browser installation failed and staging cleanup also failed");
+}
+async function publishVerifiedBrowser(lease, installation, staging) {
+    const { cacheDirectory, hostPlatform, installBrowser, target } = installation;
+    try {
+        const staged = await installBrowser({
+            browser: target.browser,
+            buildId: BROWSER_BUILD,
+            cacheDir: staging,
+            expectedHash: target.sha256,
+            platform: target.browserPlatform,
+        });
+        if (!(await isExecutable(staged.executablePath, hostPlatform))) {
+            throw new BrowserInstallError("the verified browser archive did not produce an executable");
+        }
+        const destination = installedBrowser(cacheDirectory, target.browser, target.browserPlatform);
+        await mkdir(dirname(destination.path), { recursive: true });
+        await verifyInstallLease(lease);
+        await rename(staged.path, destination.path);
+        if (!(await isExecutable(destination.executablePath, hostPlatform))) {
+            throw new BrowserInstallError("the published browser installation has no executable");
+        }
+        return destination.executablePath;
+    }
+    catch (error) {
+        if (error instanceof BrowserInstallError) {
+            throw error;
+        }
+        throw new BrowserInstallError(`failed to install ${target.browser} ${BROWSER_BUILD}`, error);
+    }
+}
+async function removeAbandonedStaging(cacheDirectory) {
+    const entries = await readdir(cacheDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith(INSTALL_STAGING_PREFIX)) {
+            await rm(join(cacheDirectory, entry.name), {
+                force: true,
+                recursive: true,
+            });
+        }
+    }
+}
+function installedBrowser(cacheDirectory, browser, platform) {
+    return new InstalledBrowser(new Cache(cacheDirectory), browser, BROWSER_BUILD, platform);
+}
+async function removeIncompleteInstall(installed) {
+    try {
+        await access(installed.path, constants.F_OK);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+    await rm(installed.path, { force: true, recursive: true });
+}
+async function isExecutable(path, hostPlatform) {
+    try {
+        const metadata = await stat(path);
+        if (!metadata.isFile()) {
+            return false;
+        }
+        await access(path, hostPlatform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Cross-process installation lease
+async function withInstallLock(cacheDirectory, action, timings = INSTALL_LOCK_TIMINGS) {
+    const lock = join(cacheDirectory, ".install.lock");
+    const lease = await acquireInstallLock(lock, timings);
+    const heartbeat = setInterval(() => {
+        void refreshInstallLease(lease);
+    }, timings.heartbeatMilliseconds);
+    heartbeat.unref();
+    return withObservedCleanup(() => action(lease), async () => {
+        clearInterval(heartbeat);
+        await releaseInstallLock(lease);
+    }, "browser installation failed and lease cleanup also failed");
+}
+async function refreshInstallLease(lease) {
+    const now = new Date();
+    try {
+        await utimes(lease.marker, now, now);
+    }
+    catch {
+        // A reclaimer may have moved this exact lease. The owner-specific marker
+        // prevents the resumed heartbeat from touching a successor's lock.
+    }
+}
+async function verifyInstallLease(lease) {
+    const now = new Date();
+    try {
+        await utimes(lease.marker, now, now);
+    }
+    catch (error) {
+        throw new BrowserInstallError("browser installation lease was lost before cache publication", error);
+    }
+}
+async function acquireInstallLock(lock, timings) {
+    const deadline = Date.now() + timings.waitMilliseconds;
+    while (Date.now() < deadline) {
+        const lease = await tryAcquireInstallLock(lock);
+        if (lease !== undefined) {
+            return lease;
+        }
+        await reclaimAbandonedLock(lock, timings.staleMilliseconds);
+        await delay(timings.pollMilliseconds);
+    }
+    throw new BrowserInstallError("another Onmark process is still installing the browser");
+}
+async function tryAcquireInstallLock(lock) {
+    const owner = randomUUID();
+    const candidate = `${lock}.candidate-${owner}`;
+    const markerName = `${INSTALL_LOCK_OWNER_PREFIX}${owner}`;
+    await mkdir(candidate);
+    return withObservedCleanup(async () => {
+        try {
+            await writeFile(join(candidate, markerName), "", { flag: "wx" });
+        }
+        catch (error) {
+            throw new BrowserInstallError("failed to prepare the browser installation lock", error);
+        }
+        try {
+            await rename(candidate, lock);
+        }
+        catch (error) {
+            if (isLockContention(error) || (await installLockExists(lock))) {
+                return undefined;
+            }
+            throw new BrowserInstallError("failed to acquire the browser installation lock", error);
+        }
+        return {
+            directory: lock,
+            marker: join(lock, markerName),
+        };
+    }, () => rm(candidate, { force: true, recursive: true }), "browser installation lock acquisition and candidate cleanup both failed");
+}
+async function releaseInstallLock(lease) {
+    await rm(lease.marker, { force: true });
+    try {
+        await rmdir(lease.directory);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT") ||
+            isErrno(error, "ENOTEMPTY") ||
+            isErrno(error, "EEXIST")) {
+            return;
+        }
+        throw error;
+    }
+}
+async function reclaimAbandonedLock(lock, staleMilliseconds) {
+    let modified;
+    try {
+        modified = await installLockModifiedAt(lock);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+    if (Date.now() - modified <= staleMilliseconds) {
+        return;
+    }
+    const abandoned = `${lock}.abandoned-${randomUUID()}`;
+    try {
+        await rename(lock, abandoned);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+    await rm(abandoned, { force: true, recursive: true });
+}
+async function installLockModifiedAt(lock) {
+    const owners = (await readdir(lock))
+        .filter((entry) => entry.startsWith(INSTALL_LOCK_OWNER_PREFIX))
+        .sort();
+    const owner = owners[0];
+    if (owners.length === 1 && owner !== undefined) {
+        return (await stat(join(lock, owner))).mtimeMs;
+    }
+    return (await stat(lock)).mtimeMs;
+}
+function isLockContention(error) {
+    return isErrno(error, "EEXIST") || isErrno(error, "ENOTEMPTY");
+}
+async function installLockExists(lock) {
+    try {
+        return (await stat(lock)).isDirectory();
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return false;
+        }
+        throw new BrowserInstallError("failed to inspect the browser installation lock", error);
+    }
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+async function withObservedCleanup(action, cleanup, combinedMessage) {
+    let outcome;
+    try {
+        outcome = { status: "fulfilled", value: await action() };
+    }
+    catch (error) {
+        outcome = { reason: error, status: "rejected" };
+    }
+    try {
+        await cleanup();
+    }
+    catch (cleanupError) {
+        if (outcome.status === "fulfilled") {
+            throw cleanupError;
+        }
+        throw new AggregateError([outcome.reason, cleanupError], combinedMessage);
+    }
+    if (outcome.status === "rejected") {
+        throw outcome.reason;
+    }
+    return outcome.value;
+}

package/packages/launcher/dist/src/cache.d.ts

@@ -0,0 +1,8 @@
+import type { ReleaseHost } from "./release.js";
+export interface CacheEnvironment {
+    readonly localAppData?: string;
+    readonly windowsDirectory?: string;
+    readonly xdgCacheHome?: string;
+}
+export declare function frameCacheDirectory(host: ReleaseHost, homeDirectory: string, environment: CacheEnvironment): string;
+export declare function browserCacheDirectory(host: ReleaseHost, homeDirectory: string, environment: CacheEnvironment): string;

package/packages/launcher/dist/src/cache.js

@@ -0,0 +1,21 @@
+// Host cache selection keeps platform conventions out of browser installation.
+import { posix, win32 } from "node:path";
+export function frameCacheDirectory(host, homeDirectory, environment) {
+    return cacheDirectory(host, homeDirectory, environment, "frames");
+}
+export function browserCacheDirectory(host, homeDirectory, environment) {
+    return cacheDirectory(host, homeDirectory, environment, "browser");
+}
+function cacheDirectory(host, homeDirectory, environment, leaf) {
+    switch (host.platform) {
+        case "darwin":
+            return posix.join(homeDirectory, "Library", "Caches", "onmark", leaf);
+        case "linux":
+            return posix.join(environment.xdgCacheHome ?? posix.join(homeDirectory, ".cache"), "onmark", leaf);
+        case "win32":
+            return win32.join(environment.localAppData ??
+                win32.join(homeDirectory, "AppData", "Local"), "onmark", leaf);
+        default:
+            return posix.join(homeDirectory, ".onmark", leaf);
+    }
+}

package/packages/launcher/dist/src/capture-environment.d.ts

@@ -0,0 +1,15 @@
+import { type CacheEnvironment } from "./cache.js";
+import { type ReleaseHost } from "./release.js";
+export interface CaptureEnvironmentOptions {
+    readonly cacheEnvironment: CacheEnvironment;
+    readonly fontDirectories?: readonly string[];
+    readonly homeDirectory: string;
+    readonly host: ReleaseHost;
+    readonly osRelease: string;
+}
+export interface LocalCaptureEnvironment {
+    readonly cacheDirectory: string;
+    readonly seed: string;
+}
+/** Computes the release-owned seed consumed by the native capture boundary. */
+export declare function captureEnvironment(options: CaptureEnvironmentOptions): Promise<LocalCaptureEnvironment>;

package/packages/launcher/dist/src/capture-environment.js

@@ -0,0 +1,145 @@
+// Desktop capture identity commits local cache reuse to pixel-affecting host facts.
+import { createHash } from "node:crypto";
+import { lstat, readdir, readlink } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { frameCacheDirectory } from "./cache.js";
+import { BROWSER_BUILD, desktopTarget } from "./release.js";
+const IDENTITY_DOMAIN = "onmark-desktop-capture-environment-v1";
+const MAX_FONT_ENTRIES = 100_000;
+/** Computes the release-owned seed consumed by the native capture boundary. */
+export async function captureEnvironment(options) {
+    const target = desktopTarget(options.host);
+    const hash = createHash("sha256");
+    record(hash, IDENTITY_DOMAIN);
+    record(hash, options.host.platform);
+    record(hash, options.host.arch);
+    record(hash, options.osRelease);
+    record(hash, BROWSER_BUILD);
+    record(hash, target.browser);
+    record(hash, target.browserPlatform);
+    record(hash, target.sha256);
+    const directories = options.fontDirectories ??
+        systemFontDirectories(options.host, options.homeDirectory, options.cacheEnvironment);
+    const state = { entries: 0 };
+    for (const [index, directory] of directories.entries()) {
+        await scanFontTree(hash, state, directory, index, "");
+    }
+    return Object.freeze({
+        cacheDirectory: frameCacheDirectory(options.host, options.homeDirectory, options.cacheEnvironment),
+        seed: `sha256:${hash.digest("hex")}`,
+    });
+}
+// ── Font inventory
+async function scanFontTree(hash, state, root, rootIndex, relative) {
+    const paths = optionsPath(root);
+    const directory = relative.length === 0 ? root : paths.join(root, relative);
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        record(hash, `unreadable:${rootIndex}:${relative}:${errorCode(error)}`);
+        return;
+    }
+    entries.sort((left, right) => compareNames(left.name, right.name));
+    for (const entry of entries) {
+        state.entries += 1;
+        if (state.entries > MAX_FONT_ENTRIES) {
+            throw new Error(`font inventory exceeds the ${MAX_FONT_ENTRIES}-entry capture limit`);
+        }
+        const child = relative.length === 0 ? entry.name : paths.join(relative, entry.name);
+        const absolute = paths.join(root, child);
+        let metadata;
+        try {
+            metadata = await lstat(absolute, { bigint: true });
+        }
+        catch (error) {
+            record(hash, `missing:${rootIndex}:${portable(child)}:${errorCode(error)}`);
+            continue;
+        }
+        const identity = [
+            fontEntryKind(metadata),
+            rootIndex,
+            portable(child),
+            metadata.size,
+            metadata.mtimeNs,
+        ];
+        record(hash, identity.join(":"));
+        if (metadata.isDirectory()) {
+            await scanFontTree(hash, state, root, rootIndex, child);
+        }
+        else if (metadata.isSymbolicLink()) {
+            try {
+                record(hash, `target:${await readlink(absolute)}`);
+            }
+            catch (error) {
+                record(hash, `target-unreadable:${errorCode(error)}`);
+            }
+        }
+    }
+}
+function fontEntryKind(metadata) {
+    if (metadata.isDirectory()) {
+        return "directory";
+    }
+    if (metadata.isSymbolicLink()) {
+        return "symlink";
+    }
+    return "file";
+}
+function systemFontDirectories(host, homeDirectory, environment) {
+    switch (host.platform) {
+        case "darwin":
+            return [
+                "/System/Library/Fonts",
+                "/Library/Fonts",
+                posix.join(homeDirectory, "Library", "Fonts"),
+            ];
+        case "linux":
+            return [
+                "/usr/share/fonts",
+                "/usr/local/share/fonts",
+                posix.join(homeDirectory, ".local", "share", "fonts"),
+                posix.join(homeDirectory, ".fonts"),
+            ];
+        case "win32": {
+            const windows = environment.windowsDirectory ?? "C:\\Windows";
+            return [
+                win32.join(windows, "Fonts"),
+                win32.join(environment.localAppData ??
+                    win32.join(homeDirectory, "AppData", "Local"), "Microsoft", "Windows", "Fonts"),
+            ];
+        }
+        default:
+            return [];
+    }
+}
+// ── Canonical values
+function compareNames(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+}
+function optionsPath(root) {
+    return /^[A-Za-z]:\\/u.test(root) ? win32 : posix;
+}
+function portable(path) {
+    return path.replaceAll("\\", "/");
+}
+function record(hash, value) {
+    const bytes = Buffer.from(value, "utf8");
+    const length = Buffer.allocUnsafe(4);
+    length.writeUInt32BE(bytes.byteLength);
+    hash.update(length);
+    hash.update(bytes);
+}
+function errorCode(error) {
+    if (error instanceof Error && "code" in error) {
+        return String(error.code);
+    }
+    return "unknown";
+}

package/packages/launcher/dist/src/command.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/packages/launcher/dist/src/command.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// npm release boundary resolves product tools before delegating to native CLI.
+import { createRequire } from "node:module";
+import { homedir, release } from "node:os";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { captureEnvironment } from "./capture-environment.js";
+import { platformArtifact } from "./platform.js";
+import { runNative } from "./native.js";
+try {
+    const host = { arch: process.arch, platform: process.platform };
+    const releasePackage = createRequire(new URL("../../../../package.json", import.meta.url));
+    const artifact = platformArtifact(host, createRequire(import.meta.url).resolve);
+    const browserProvisioner = fileURLToPath(new URL("./browser-command.js", import.meta.url));
+    const bundler = releasePackage.resolve("#onmark-bundler-command");
+    const localCapture = await captureEnvironment({
+        cacheEnvironment: cacheEnvironment(process.env),
+        homeDirectory: homedir(),
+        host,
+        osRelease: release(),
+    });
+    const result = await runNative(process.argv.slice(2), {
+        browserProvisioner,
+        bundler,
+        ffmpeg: artifact.ffmpeg,
+        ffprobe: artifact.ffprobe,
+        nativeCli: artifact.nativeCli,
+        node: process.execPath,
+    }, {
+        ...process.env,
+        ONMARK_CAPTURE_ENVIRONMENT_SEED: localCapture.seed,
+        ONMARK_FRAME_CACHE: localCapture.cacheDirectory,
+    });
+    if (result.signal !== null) {
+        process.kill(process.pid, result.signal);
+    }
+    else {
+        process.exitCode = result.code ?? 1;
+    }
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : "unknown launcher failure";
+    process.stderr.write(`onmark: ${message}\n`);
+    process.exitCode = 1;
+}
+function cacheEnvironment(environment) {
+    return {
+        ...(environment["LOCALAPPDATA"] === undefined
+            ? {}
+            : { localAppData: environment["LOCALAPPDATA"] }),
+        ...(environment["WINDIR"] === undefined
+            ? {}
+            : { windowsDirectory: environment["WINDIR"] }),
+        ...(environment["XDG_CACHE_HOME"] === undefined
+            ? {}
+            : { xdgCacheHome: environment["XDG_CACHE_HOME"] }),
+    };
+}

package/packages/launcher/dist/src/native.d.ts

@@ -0,0 +1,20 @@
+import { type SpawnOptions } from "node:child_process";
+export interface ProductTools {
+    readonly browserProvisioner: string;
+    readonly bundler: string;
+    readonly ffmpeg: string;
+    readonly ffprobe: string;
+    readonly nativeCli: string;
+    readonly node: string;
+}
+export interface NativeResult {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+}
+export interface NativeInvocation {
+    readonly arguments: readonly string[];
+    readonly command: string;
+    readonly options: SpawnOptions;
+}
+export declare function nativeInvocation(arguments_: readonly string[], tools: ProductTools, environment: NodeJS.ProcessEnv): NativeInvocation;
+export declare function runNative(arguments_: readonly string[], tools: ProductTools, environment: NodeJS.ProcessEnv): Promise<NativeResult>;

package/packages/launcher/dist/src/native.js

@@ -0,0 +1,31 @@
+// Native process ownership preserves Rust CLI semantics and terminal behavior.
+import { spawn } from "node:child_process";
+export function nativeInvocation(arguments_, tools, environment) {
+    const options = {
+        env: {
+            ...environment,
+            ONMARK_BROWSER_PROVISIONER: tools.node,
+            ONMARK_BROWSER_PROVISIONER_ENTRY: tools.browserProvisioner,
+            ONMARK_BUNDLER: tools.node,
+            ONMARK_BUNDLER_ENTRY: tools.bundler,
+            ONMARK_FFMPEG: tools.ffmpeg,
+            ONMARK_FFPROBE: tools.ffprobe,
+        },
+        stdio: "inherit",
+    };
+    return Object.freeze({
+        arguments: Object.freeze([...arguments_]),
+        command: tools.nativeCli,
+        options,
+    });
+}
+export async function runNative(arguments_, tools, environment) {
+    const invocation = nativeInvocation(arguments_, tools, environment);
+    const child = spawn(invocation.command, invocation.arguments, invocation.options);
+    return new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            resolve(Object.freeze({ code, signal }));
+        });
+    });
+}

package/packages/launcher/dist/src/platform.d.ts

@@ -0,0 +1,13 @@
+import { type ReleaseHost } from "./release.js";
+export { UnsupportedReleaseTargetError } from "./release.js";
+export interface PlatformArtifact {
+    readonly ffmpeg: string;
+    readonly ffprobe: string;
+    readonly nativeCli: string;
+    readonly packageName: string;
+}
+type PackageResolver = (specifier: string) => string;
+export declare class MissingPlatformArtifactError extends Error {
+    constructor(packageName: string, cause: unknown);
+}
+export declare function platformArtifact(host: ReleaseHost, resolvePackage: PackageResolver): PlatformArtifact;

package/packages/launcher/dist/src/platform.js

@@ -0,0 +1,29 @@
+// Platform release artifacts keep native tools out of the portable npm facade.
+import { posix, win32 } from "node:path";
+import { desktopTarget } from "./release.js";
+export { UnsupportedReleaseTargetError } from "./release.js";
+export class MissingPlatformArtifactError extends Error {
+    constructor(packageName, cause) {
+        super(`Onmark's platform package ${packageName} is missing; reinstall onmark without omitting optional dependencies`, { cause });
+        this.name = "MissingPlatformArtifactError";
+    }
+}
+export function platformArtifact(host, resolvePackage) {
+    const target = desktopTarget(host);
+    const paths = host.platform === "win32" ? win32 : posix;
+    let packageRoot;
+    try {
+        packageRoot = paths.dirname(resolvePackage(`${target.packageName}/package.json`));
+    }
+    catch (error) {
+        throw new MissingPlatformArtifactError(target.packageName, error);
+    }
+    const extension = host.platform === "win32" ? ".exe" : "";
+    const executable = (name) => paths.join(packageRoot, "bin", `${name}${extension}`);
+    return Object.freeze({
+        ffmpeg: executable("ffmpeg"),
+        ffprobe: executable("ffprobe"),
+        nativeCli: executable("onmark"),
+        packageName: target.packageName,
+    });
+}

package/packages/launcher/dist/src/release.d.ts

@@ -0,0 +1,16 @@
+import { Browser, BrowserPlatform } from "@puppeteer/browsers";
+export interface ReleaseHost {
+    readonly arch: NodeJS.Architecture;
+    readonly platform: NodeJS.Platform;
+}
+export interface DesktopTarget {
+    readonly browser: Browser;
+    readonly browserPlatform: BrowserPlatform;
+    readonly packageName: string;
+    readonly sha256: string;
+}
+export declare const BROWSER_BUILD: string;
+export declare class UnsupportedReleaseTargetError extends Error {
+    constructor(host: ReleaseHost);
+}
+export declare function desktopTarget(host: ReleaseHost): DesktopTarget;