@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/launcher/commands.js

@@ -1,260 +0,0 @@
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { HOST_PROTOCOL, LAUNCHER_PROTOCOL, } from "@nylorun/core/compatibility";
-import { TENANT_SCHEMA_VERSION } from "../tenant/schema.js";
-import { RUNTIME_VERSION } from "../version.js";
-import { LauncherError, UsageError } from "./errors.js";
-import { down, restart, run, up } from "./lifecycle.js";
-import { logs } from "./logs.js";
-import { emitError, emitEvent, emitResult, exitCodeFor, } from "./output.js";
-import { ensureHostLayout, hostPaths } from "./paths.js";
-import { status } from "./status.js";
-export const launcherUsage = `Usage: nylorun-runtime [--home <dir>] [--json] <command>
-
-Commands:
-  version                  also --version
-  up [--port <n>] [--allow-downgrade]
-  down [--wait [--timeout <s>]] [--force]
-  restart [--port <n>] [--allow-downgrade] [--wait | --force]
-  run [--port <n>] [--allow-downgrade]
-  status
-  logs [--lines <n>] [--follow] [--tenant <id> | --all]`;
-/** The Runtime needs node:sqlite and Node 24 APIs. */
-const MIN_NODE_MAJOR = 24;
-function usage(message) {
-    throw new UsageError(`${message}\n\n${launcherUsage}`);
-}
-function parseGlobal(args) {
-    const rest = [];
-    let json = false;
-    let home;
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        if (arg === "--json") {
-            json = true;
-            continue;
-        }
-        if (arg === "--home") {
-            const value = args[++index];
-            if (!value || value.startsWith("-"))
-                usage("--home requires a directory.");
-            home = value;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h") {
-            throw new UsageError(launcherUsage, "");
-        }
-        rest.push(arg === "--version" && rest.length === 0 ? "version" : arg);
-    }
-    return { rest, booleans: new Set(), values: new Map(), json, home };
-}
-function parseCommandFlags(args, allowed = {}) {
-    const booleans = new Set();
-    const values = new Map();
-    const rest = [];
-    const booleanNames = new Set(allowed.booleans ?? []);
-    const valueNames = new Set(allowed.values ?? []);
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        if (!arg.startsWith("-")) {
-            rest.push(arg);
-            continue;
-        }
-        if (booleanNames.has(arg)) {
-            if (booleans.has(arg))
-                usage(`${arg} may only be supplied once.`);
-            booleans.add(arg);
-            continue;
-        }
-        if (valueNames.has(arg)) {
-            if (values.has(arg))
-                usage(`${arg} may only be supplied once.`);
-            const value = args[++index];
-            if (!value || value.startsWith("-"))
-                usage(`${arg} requires a value.`);
-            values.set(arg, value);
-            continue;
-        }
-        usage(`Unknown flag ${arg}.`);
-    }
-    return { rest, booleans, values, json: false };
-}
-function parsePort(value) {
-    if (value === undefined)
-        return undefined;
-    const port = Number(value);
-    if (!Number.isInteger(port) || port < 0 || port > 65535) {
-        usage("--port must be an integer between 0 and 65535.");
-    }
-    return port;
-}
-function lifecycleContext(paths, options, sink) {
-    return {
-        paths,
-        platform: options.platform,
-        nodeBinary: options.nodeBinary,
-        hostEntry: fileURLToPath(new URL("../host/main.js", import.meta.url)),
-        runtimeVersion: RUNTIME_VERSION,
-        tenantSchemaMax: TENANT_SCHEMA_VERSION,
-        baselineEnv: options.baselineEnv,
-        emit: (event) => emitEvent(sink, event),
-        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
-        ...(options.lifecycle ?? {}),
-    };
-}
-/**
- * Run launcher commands. Returns a process exit code (0, 1, or 2).
- * Ambient values must already be resolved into `options`.
- */
-export async function runLauncher(argv, options) {
-    const sink = options.sink;
-    try {
-        const global = parseGlobal(argv);
-        sink.json = global.json || sink.json;
-        const home = resolve(global.home ?? options.home);
-        const paths = hostPaths(home);
-        const [verb, ...rest] = global.rest;
-        if (!verb)
-            usage("Missing command.");
-        if (verb === "version") {
-            const flags = parseCommandFlags(rest);
-            if (flags.rest.length)
-                usage("version takes no arguments.");
-            emitResult(sink, {
-                runtimeVersion: options.lifecycle?.runtimeVersion ?? RUNTIME_VERSION,
-                launcherProtocol: LAUNCHER_PROTOCOL,
-                protocol: HOST_PROTOCOL,
-                node: options.nodeVersion,
-            });
-            return 0;
-        }
-        const nodeMajor = Number(options.nodeVersion.split(".")[0]);
-        if (!(nodeMajor >= MIN_NODE_MAJOR)) {
-            throw new LauncherError("platform_unsupported", `Node ${MIN_NODE_MAJOR} or newer is required to run the Nylorun Runtime (found ${options.nodeVersion}).`, `Install Node ${MIN_NODE_MAJOR}, then reinstall: npm install --global @nylorun/runtime`);
-        }
-        if (verb === "status") {
-            const flags = parseCommandFlags(rest);
-            if (flags.rest.length)
-                usage("status takes no arguments.");
-            const result = await status(paths, options.lifecycle?.runtimeVersion ?? RUNTIME_VERSION);
-            emitResult(sink, { ...result });
-            return 0;
-        }
-        if (verb === "logs") {
-            const flags = parseCommandFlags(rest, {
-                booleans: ["--follow", "-f", "--all"],
-                values: ["--lines", "-n", "--tenant"],
-            });
-            if (flags.rest.length)
-                usage("logs takes no positional arguments.");
-            if (flags.booleans.has("--all") && flags.values.has("--tenant")) {
-                usage("Use either --tenant or --all, not both.");
-            }
-            const linesRaw = flags.values.get("--lines") ?? flags.values.get("-n");
-            let lines;
-            if (linesRaw !== undefined) {
-                lines = Number(linesRaw);
-                if (!Number.isInteger(lines) || lines < 0) {
-                    usage("--lines must be a non-negative integer.");
-                }
-            }
-            await logs(paths, {
-                ...(lines !== undefined ? { lines } : {}),
-                follow: flags.booleans.has("--follow") || flags.booleans.has("-f"),
-                all: flags.booleans.has("--all"),
-                ...(flags.values.has("--tenant")
-                    ? { tenant: flags.values.get("--tenant") }
-                    : {}),
-                ...(options.signal ? { signal: options.signal } : {}),
-                emit: (event) => emitEvent(sink, event),
-            });
-            return 0;
-        }
-        if (verb === "up") {
-            const flags = parseCommandFlags(rest, {
-                booleans: ["--allow-downgrade"],
-                values: ["--port"],
-            });
-            if (flags.rest.length)
-                usage("up takes no positional arguments.");
-            const port = parsePort(flags.values.get("--port"));
-            const result = await up(lifecycleContext(paths, options, sink), {
-                ...(port !== undefined ? { port } : {}),
-                allowDowngrade: flags.booleans.has("--allow-downgrade"),
-            });
-            emitResult(sink, { ...result });
-            return 0;
-        }
-        if (verb === "down") {
-            const flags = parseCommandFlags(rest, {
-                booleans: ["--wait", "--force"],
-                values: ["--timeout"],
-            });
-            if (flags.rest.length)
-                usage("down takes no positional arguments.");
-            let timeoutMs;
-            if (flags.values.has("--timeout")) {
-                const seconds = Number(flags.values.get("--timeout"));
-                if (!Number.isFinite(seconds) || seconds <= 0) {
-                    usage("--timeout must be a positive number of seconds.");
-                }
-                timeoutMs = seconds * 1000;
-            }
-            const result = await down(lifecycleContext(paths, options, sink), {
-                wait: flags.booleans.has("--wait"),
-                force: flags.booleans.has("--force"),
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            });
-            emitResult(sink, { ...result });
-            return 0;
-        }
-        if (verb === "restart") {
-            const flags = parseCommandFlags(rest, {
-                booleans: ["--allow-downgrade", "--wait", "--force"],
-                values: ["--timeout", "--port"],
-            });
-            if (flags.rest.length)
-                usage("restart takes no positional arguments.");
-            let timeoutMs;
-            if (flags.values.has("--timeout")) {
-                const seconds = Number(flags.values.get("--timeout"));
-                if (!Number.isFinite(seconds) || seconds <= 0) {
-                    usage("--timeout must be a positive number of seconds.");
-                }
-                timeoutMs = seconds * 1000;
-            }
-            const port = parsePort(flags.values.get("--port"));
-            const result = await restart(lifecycleContext(paths, options, sink), {
-                allowDowngrade: flags.booleans.has("--allow-downgrade"),
-                wait: flags.booleans.has("--wait"),
-                force: flags.booleans.has("--force"),
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-                ...(port !== undefined ? { port } : {}),
-            });
-            emitResult(sink, { ...result });
-            return 0;
-        }
-        if (verb === "run") {
-            const flags = parseCommandFlags(rest, {
-                booleans: ["--allow-downgrade"],
-                values: ["--port"],
-            });
-            if (flags.rest.length)
-                usage("run takes no positional arguments.");
-            const port = parsePort(flags.values.get("--port"));
-            const ctx = lifecycleContext(paths, options, sink);
-            const result = await run(ctx, {
-                ...(port !== undefined ? { port } : {}),
-                allowDowngrade: flags.booleans.has("--allow-downgrade"),
-                onReady: (ready) => emitResult(sink, { ...ready }),
-            });
-            void result;
-            return 0;
-        }
-        usage(`Unknown command ${verb}.`);
-    }
-    catch (error) {
-        emitError(sink, error instanceof Error ? error : new Error(String(error)));
-        return exitCodeFor(error);
-    }
-}

package/dist/launcher/ensure-config.d.ts

@@ -1,16 +0,0 @@
-import { type HostConfigFile } from "./host-config.js";
-import { type HostPaths } from "./paths.js";
-export interface EnsureHostConfigOptions {
-    /** Explicit `--port`; collision fails (strict). `0` means pick a free port. */
-    port?: number;
-    host?: string;
-}
-/**
- * Load or create host.json. On first setup prefer 8787; when taken, pick a free
- * loopback port. Explicit `--port` is strict (except `0` = free port).
- */
-export declare function ensureHostConfig(paths: HostPaths, options?: EnsureHostConfigOptions): Promise<{
-    config: HostConfigFile;
-    created: boolean;
-    portSelected: boolean;
-}>;

package/dist/launcher/ensure-config.js

@@ -1,79 +0,0 @@
-import { createServer } from "node:net";
-import { LauncherError } from "./errors.js";
-import { newHostId, readHostConfig, writeHostConfig, } from "./host-config.js";
-import { hostUrl } from "./paths.js";
-import { portBindable, probeHostHealth } from "./probe.js";
-import { ensureHostLayout } from "./paths.js";
-const DEFAULT_HOST = "127.0.0.1";
-const DEFAULT_PORT = 8787;
-async function findFreeLoopbackPort(host) {
-    const server = createServer();
-    return await new Promise((resolvePromise, reject) => {
-        server.once("error", reject);
-        server.listen(0, host, () => {
-            const address = server.address();
-            if (!address || typeof address === "string") {
-                server.close();
-                reject(new Error("Could not allocate a free loopback port."));
-                return;
-            }
-            const { port } = address;
-            server.close(() => resolvePromise(port));
-        });
-    });
-}
-/**
- * Load or create host.json. On first setup prefer 8787; when taken, pick a free
- * loopback port. Explicit `--port` is strict (except `0` = free port).
- */
-export async function ensureHostConfig(paths, options = {}) {
-    await ensureHostLayout(paths);
-    const existing = await readHostConfig(paths);
-    if (existing) {
-        if (options.port !== undefined && options.port !== 0 && options.port !== existing.port) {
-            const updated = {
-                ...existing,
-                format: 1,
-                port: options.port,
-            };
-            if (!(await portBindable(updated.host, updated.port))) {
-                const probe = await probeHostHealth(hostUrl(updated));
-                if (!probe.health || probe.health.hostId !== updated.hostId) {
-                    throw new LauncherError("foreign_port", `Port ${updated.port} on ${updated.host} is in use by another process.`, 'Choose a free port with "nylorun-runtime up --port <n>".');
-                }
-            }
-            await writeHostConfig(paths, updated);
-            return { config: updated, created: false, portSelected: false };
-        }
-        return {
-            config: { ...existing, format: 1 },
-            created: false,
-            portSelected: false,
-        };
-    }
-    const host = options.host ?? DEFAULT_HOST;
-    let port = options.port === 0 ? await findFreeLoopbackPort(host) : (options.port ?? DEFAULT_PORT);
-    let portSelected = options.port === 0;
-    if (options.port !== undefined && options.port !== 0) {
-        if (!(await portBindable(host, port))) {
-            throw new LauncherError("foreign_port", `Port ${port} on ${host} is in use by another process.`, 'Choose a free port with "nylorun-runtime up --port <n>".');
-        }
-    }
-    else if (options.port === undefined) {
-        if (!(await portBindable(host, port))) {
-            const probe = await probeHostHealth(hostUrl({ host, port }));
-            if (probe.foreign || probe.health || !(await portBindable(host, port))) {
-                port = await findFreeLoopbackPort(host);
-                portSelected = true;
-            }
-        }
-    }
-    const config = {
-        format: 1,
-        hostId: newHostId(),
-        host,
-        port,
-    };
-    await writeHostConfig(paths, config);
-    return { config, created: true, portSelected };
-}

package/dist/launcher/errors.d.ts

@@ -1,12 +0,0 @@
-import type { ErrorCode } from "@nylorun/core/compatibility";
-/** Operational launcher failure (exit 1). Usage errors are separate (exit 2). */
-export declare class LauncherError extends Error {
-    readonly code: ErrorCode;
-    readonly remedy: string;
-    readonly details?: unknown;
-    constructor(code: ErrorCode, message: string, remedy: string, details?: unknown);
-}
-export declare class UsageError extends Error {
-    readonly remedy: string;
-    constructor(message: string, remedy?: string);
-}

package/dist/launcher/errors.js

@@ -1,22 +0,0 @@
-/** Operational launcher failure (exit 1). Usage errors are separate (exit 2). */
-export class LauncherError extends Error {
-    code;
-    remedy;
-    details;
-    constructor(code, message, remedy, details) {
-        super(message);
-        this.name = "LauncherError";
-        this.code = code;
-        this.remedy = remedy;
-        if (details !== undefined)
-            this.details = details;
-    }
-}
-export class UsageError extends Error {
-    remedy;
-    constructor(message, remedy = "See nylorun-runtime --help.") {
-        super(message);
-        this.name = "UsageError";
-        this.remedy = remedy;
-    }
-}

package/dist/launcher/host-config.d.ts

@@ -1,17 +0,0 @@
-import type { HostPaths } from "./paths.js";
-import type { HostConfigFileV1 } from "./protocol.js";
-export type HostConfigFile = HostConfigFileV1 & Record<string, unknown>;
-export declare const HOST_ID_PATTERN: RegExp;
-export declare function newHostId(): string;
-export declare function isHostId(value: unknown): value is string;
-/**
- * Read host.json. Missing `format` means Tenants-era format 0.
- * Returns undefined when absent or structurally invalid.
- */
-export declare function readHostConfig(paths: HostPaths): Promise<HostConfigFile | undefined>;
-/**
- * Write host.json at format 1. Upgrades format 0, keeps unknown fields, and
- * refuses files with a newer format (`host_format_newer`).
- */
-export declare function writeHostConfig(paths: HostPaths, config: HostConfigFile): Promise<void>;
-export declare function hostConfigFormat(config: HostConfigFile): number;

package/dist/launcher/host-config.js

@@ -1,64 +0,0 @@
-import { randomBytes } from "node:crypto";
-import { readFile, rename, writeFile } from "node:fs/promises";
-import { newTenantId } from "@nylorun/core/compatibility";
-import { LauncherError } from "./errors.js";
-const KNOWN_FORMAT = 1;
-export const HOST_ID_PATTERN = /^host_[0-9a-hjkmnp-tv-z]{26}$/;
-export function newHostId() {
-    return `host_${newTenantId().slice(3)}`;
-}
-export function isHostId(value) {
-    return typeof value === "string" && HOST_ID_PATTERN.test(value);
-}
-function formatOf(value) {
-    if (value.format === undefined)
-        return 0;
-    if (typeof value.format === "number" && Number.isInteger(value.format)) {
-        return value.format;
-    }
-    return Number.POSITIVE_INFINITY;
-}
-/**
- * Read host.json. Missing `format` means Tenants-era format 0.
- * Returns undefined when absent or structurally invalid.
- */
-export async function readHostConfig(paths) {
-    try {
-        const value = JSON.parse(await readFile(paths.config, "utf8"));
-        if (typeof value.hostId !== "string" ||
-            typeof value.host !== "string" ||
-            typeof value.port !== "number") {
-            return undefined;
-        }
-        return value;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Write host.json at format 1. Upgrades format 0, keeps unknown fields, and
- * refuses files with a newer format (`host_format_newer`).
- */
-export async function writeHostConfig(paths, config) {
-    const existing = await readHostConfig(paths);
-    if (existing) {
-        const existingFormat = formatOf(existing);
-        if (existingFormat > KNOWN_FORMAT) {
-            throw new LauncherError("host_format_newer", `host.json format ${existingFormat} is newer than this launcher supports (${KNOWN_FORMAT}).`, "Upgrade the Runtime (npm install --global @nylorun/runtime@latest), then retry.", { format: existingFormat, known: KNOWN_FORMAT });
-        }
-    }
-    const merged = {
-        ...(existing ?? {}),
-        ...config,
-        format: 1,
-    };
-    const temporary = `${paths.config}.${randomBytes(8).toString("hex")}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(merged, null, 2)}\n`, {
-        mode: 0o600,
-    });
-    await rename(temporary, paths.config);
-}
-export function hostConfigFormat(config) {
-    return formatOf(config);
-}

package/dist/launcher/host-state.d.ts

@@ -1,17 +0,0 @@
-import type { HostPaths } from "./paths.js";
-export interface HostStateFile {
-    pid: number;
-    startedAt: string;
-    version: string;
-    entry: string;
-    url: string;
-}
-export interface HostCredentialsFile {
-    adminKey: string;
-}
-export declare function readHostState(paths: HostPaths): Promise<HostStateFile | undefined>;
-export declare function writeHostState(paths: HostPaths, state: HostStateFile): Promise<void>;
-export declare function clearHostState(paths: HostPaths): Promise<void>;
-export declare function readHostCredentials(paths: HostPaths): Promise<HostCredentialsFile | undefined>;
-/** Create host-credentials.json mode 0600 if missing (Tenants D15). */
-export declare function ensureHostCredentials(paths: HostPaths): Promise<HostCredentialsFile>;

package/dist/launcher/host-state.js

@@ -1,61 +0,0 @@
-import { randomBytes } from "node:crypto";
-import { unlink } from "node:fs/promises";
-import { readFile, rename, writeFile, chmod } from "node:fs/promises";
-export async function readHostState(paths) {
-    try {
-        const value = JSON.parse(await readFile(paths.state, "utf8"));
-        return typeof value?.pid === "number" ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-export async function writeHostState(paths, state) {
-    const temporary = `${paths.state}.${randomBytes(8).toString("hex")}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, {
-        mode: 0o600,
-    });
-    await rename(temporary, paths.state);
-}
-export async function clearHostState(paths) {
-    try {
-        await unlink(paths.state);
-    }
-    catch {
-        /* absent */
-    }
-}
-export async function readHostCredentials(paths) {
-    try {
-        const value = JSON.parse(await readFile(paths.credentials, "utf8"));
-        if (typeof value?.adminKey === "string" &&
-            /^[0-9a-f]{64}$/.test(value.adminKey)) {
-            return value;
-        }
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Create host-credentials.json mode 0600 if missing (Tenants D15). */
-export async function ensureHostCredentials(paths) {
-    const existing = await readHostCredentials(paths);
-    if (existing)
-        return existing;
-    const credentials = {
-        adminKey: randomBytes(32).toString("hex"),
-    };
-    const temporary = `${paths.credentials}.${randomBytes(8).toString("hex")}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(credentials)}\n`, {
-        mode: 0o600,
-    });
-    await rename(temporary, paths.credentials);
-    try {
-        await chmod(paths.credentials, 0o600);
-    }
-    catch {
-        /* best-effort */
-    }
-    return credentials;
-}

package/dist/launcher/lifecycle.d.ts

@@ -1,66 +0,0 @@
-import { type LockOptions } from "./locks.js";
-import { type HostPaths } from "./paths.js";
-import type { DownResult, LauncherEvent, UpResult } from "./protocol.js";
-import { spawnHostProcess } from "./spawn.js";
-export type LifecycleEmit = (event: LauncherEvent) => void;
-export interface LifecycleContext {
-    paths: HostPaths;
-    platform: NodeJS.Platform;
-    /** Node that runs the Host: the launcher's own `process.execPath`. */
-    nodeBinary: string;
-    /** Host entry of this package (`dist/host/main.js`). */
-    hostEntry: string;
-    /** Version of this `@nylorun/runtime` package. */
-    runtimeVersion: string;
-    /** Highest Tenant schema this package can open. */
-    tenantSchemaMax: number;
-    /** Allowlisted ambient baseline (from main.ts). */
-    baselineEnv: Readonly<Record<string, string | undefined>>;
-    emit?: LifecycleEmit;
-    fetchImpl?: typeof fetch;
-    lock?: LockOptions;
-    /** Injectable spawn for tests. */
-    spawnHost?: typeof spawnHostProcess;
-    /** Injectable signals for `run` tests. */
-    onSignal?: (handler: (signal: NodeJS.Signals) => void) => () => void;
-}
-export interface UpOptions {
-    port?: number;
-    /** Foreground mode used by `run`. */
-    foreground?: boolean;
-    /** Start even when this Runtime is older than the one that last ran. */
-    allowDowngrade?: boolean;
-}
-/**
- * Start the local Host (D§9.6). Never restarts a running Host.
- */
-export declare function up(ctx: LifecycleContext, options?: UpOptions): Promise<UpResult>;
-export interface DownOptions {
-    wait?: boolean;
-    force?: boolean;
-    timeoutMs?: number;
-}
-/**
- * Stop the local Host (D§9.7).
- */
-export declare function down(ctx: LifecycleContext, options?: DownOptions): Promise<DownResult>;
-export interface RestartOptions {
-    allowDowngrade?: boolean;
-    wait?: boolean;
-    force?: boolean;
-    timeoutMs?: number;
-    port?: number;
-}
-/**
- * Check the installed Runtime can take over, stop, start (D§9.8).
- * runtimeVersion updates only after ready.
- */
-export declare function restart(ctx: LifecycleContext, options?: RestartOptions): Promise<UpResult>;
-/**
- * Foreground Host: print up result once ready; stop on SIGINT/SIGTERM (D§9.3).
- */
-export declare function run(ctx: LifecycleContext, options?: {
-    port?: number;
-    allowDowngrade?: boolean;
-    onReady?: (result: UpResult) => void;
-}): Promise<UpResult>;