@nylorun/runtime 0.8.0-beta → 0.10.0-beta

package/dist/host/main.js

@@ -0,0 +1,142 @@
+/**
+ * Runtime Host process entry (`@nylorun/runtime/server`).
+ *
+ * Reads only `NYLORUN_HOME` from the environment (falls back to `~/.nylorun`).
+ * Absolute Host root is resolved once and passed down.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hostPaths } from "../tenant/paths.js";
+import { createTenantModule } from "../tenant/module.js";
+import { createFsTenantStore } from "../tenant/store-fs.js";
+import { openTenantRuntime } from "../tenant/runtime.js";
+import { bootstrapPrincipal } from "../tenant/principals.js";
+import { migrateTenantDatabase } from "../tenant/schema.js";
+import { configForFactory } from "./config-for.js";
+import { createHost } from "./create-host.js";
+import { baselineEnvironment, hostProcessEnvironment, } from "./environment.js";
+import { HostListenError, EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK, } from "./http.js";
+import { createHostLogger } from "./logger.js";
+import { RUNTIME_VERSION } from "../version.js";
+const entry = fileURLToPath(import.meta.url);
+const nodeRequire = createRequire(import.meta.url);
+function coreVersion() {
+    try {
+        return nodeRequire("@nylorun/core/package.json").version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function loadJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function resolveHostRoot() {
+    const fromEnv = process.env.NYLORUN_HOME;
+    const root = fromEnv && fromEnv.length > 0 ? fromEnv : resolve(homedir(), ".nylorun");
+    return resolve(root);
+}
+export async function main() {
+    const hostRoot = resolveHostRoot();
+    const paths = hostPaths(hostRoot);
+    mkdirSync(paths.home, { recursive: true });
+    mkdirSync(paths.tmp, { recursive: true });
+    mkdirSync(paths.tenants, { recursive: true });
+    if (!existsSync(paths.config)) {
+        throw new Error(`Missing host.json at ${paths.config}; run \`nylorun runtime up\` first`);
+    }
+    if (!existsSync(paths.credentials)) {
+        throw new Error(`Missing host-credentials.json at ${paths.credentials}; run \`nylorun runtime up\` first`);
+    }
+    const config = loadJson(paths.config);
+    const credentials = loadJson(paths.credentials);
+    const logger = createHostLogger();
+    const baseline = baselineEnvironment(process.env);
+    void hostProcessEnvironment(baseline, config, paths);
+    // Credential-free release/dev fixture (create-agent / CI smokes). Requires
+    // ephemeral mode so fixture models are allowed (Tenants D10).
+    const useFixture = process.env.NYLORUN_DEV_MODEL?.trim() === "fixture";
+    const configFor = configForFactory({
+        hostRoot,
+        hostConfig: config,
+        logger,
+        baseline,
+        ...(useFixture
+            ? { mode: "ephemeral", model: { kind: "fixture" } }
+            : {}),
+    });
+    const openRuntime = (tenantConfig) => openTenantRuntime(tenantConfig);
+    const store = createFsTenantStore({
+        hostRoot,
+        openRuntime,
+        configFor,
+        logger,
+        writeBootstrap: (db, bootstrap) => {
+            migrateTenantDatabase(db);
+            bootstrapPrincipal(db, bootstrap);
+        },
+    });
+    const module = createTenantModule({
+        hostRoot,
+        store,
+        openRuntime,
+        configFor,
+        logger,
+    });
+    const options = {
+        hostRoot,
+        module,
+        config,
+        credentials,
+        logger,
+        coreVersion: coreVersion(),
+    };
+    const host = createHost(options);
+    try {
+        await host.listen();
+    }
+    catch (error) {
+        if (error instanceof HostListenError) {
+            logger.error("listen_failed", {
+                message: error.message,
+                exitCode: error.exitCode,
+            });
+            process.exitCode = error.exitCode;
+            return;
+        }
+        throw error;
+    }
+    const state = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        version: RUNTIME_VERSION,
+        entry,
+        url: host.url,
+    };
+    writeFileSync(paths.state, `${JSON.stringify(state, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    logger.info("host_ready", { url: host.url, hostId: config.hostId });
+    process.send?.({ type: "ready", url: host.url });
+    let closing;
+    const shutdown = () => {
+        closing ??= host.close().then(() => {
+            process.exit(0);
+        });
+    };
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, shutdown);
+    }
+}
+void main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    if (error instanceof HostListenError) {
+        process.exit(error.exitCode);
+    }
+    process.exit(1);
+});
+export { EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK };

package/dist/index.d.ts

@@ -1,5 +1,10 @@
-export { CoreRuntime, createRuntime, startRuntime, type RuntimeOptions } from "./core/runtime.js";
+export { openTenantRuntime, type TenantOpenHooks, } from "./tenant/runtime.js";
+export { startEphemeralRuntime, type StartEphemeralRuntimeOptions, type EphemeralRuntime, } from "./tenant/ephemeral.js";
+export type { TenantConfig, TenantHandle, TenantPaths, Logger, OpenTenantRuntime, } from "./tenant/types.js";
 export { scriptedModel, gatewayModel, type ModelProvider } from "./core/provider.js";
 export type { RuntimeAgent } from "./contracts.js";
-export { IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageBytes } from "./media.js";
+export { IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageBytes, } from "./media.js";
 export type { RuntimeModelAdapter } from "./contracts.js";
+export { baselineEnvironment, hostProcessEnvironment, tenantChildEnvironment, } from "./host/environment.js";
+export type { HostProcessPathInputs } from "./host/environment.js";
+export type { HostConfigFile, HostCredentialsFile, HostStateFile, } from "./host/config.js";

package/dist/index.js

@@ -1,3 +1,5 @@
-export { CoreRuntime, createRuntime, startRuntime } from "./core/runtime.js";
+export { openTenantRuntime, } from "./tenant/runtime.js";
+export { startEphemeralRuntime, } from "./tenant/ephemeral.js";
 export { scriptedModel, gatewayModel } from "./core/provider.js";
-export { IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageBytes } from "./media.js";
+export { IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageBytes, } from "./media.js";
+export { baselineEnvironment, hostProcessEnvironment, tenantChildEnvironment, } from "./host/environment.js";

package/dist/launcher/commands.d.ts

@@ -0,0 +1,24 @@
+import { type LifecycleContext } from "./lifecycle.js";
+import { type OutputSink } from "./output.js";
+export declare const launcherUsage = "Usage: nylorun-runtime [--home <dir>] [--json] <command>\n\nCommands:\n  version                  also --version\n  up [--port <n>] [--allow-downgrade]\n  down [--wait [--timeout <s>]] [--force]\n  restart [--port <n>] [--allow-downgrade] [--wait | --force]\n  run [--port <n>] [--allow-downgrade]\n  status\n  logs [--lines <n>] [--follow] [--tenant <id> | --all]";
+export interface LauncherRuntimeOptions {
+    home: string;
+    platform: NodeJS.Platform;
+    /** Node running this launcher (`process.execPath`); the Host runs on it. */
+    nodeBinary: string;
+    /** `process.versions.node`; the launcher refuses Node older than 24. */
+    nodeVersion: string;
+    sink: OutputSink;
+    /** Allowlisted ambient baseline from main.ts. */
+    baselineEnv: Readonly<Record<string, string | undefined>>;
+    fetchImpl?: typeof fetch;
+    /** Abort signal for logs --follow (tests). */
+    signal?: AbortSignal;
+    /** Optional lifecycle overrides for tests. */
+    lifecycle?: Partial<Pick<LifecycleContext, "spawnHost" | "onSignal" | "lock" | "fetchImpl" | "hostEntry" | "runtimeVersion" | "tenantSchemaMax">>;
+}
+/**
+ * Run launcher commands. Returns a process exit code (0, 1, or 2).
+ * Ambient values must already be resolved into `options`.
+ */
+export declare function runLauncher(argv: readonly string[], options: LauncherRuntimeOptions): Promise<number>;

package/dist/launcher/commands.js

@@ -0,0 +1,260 @@
+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

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,79 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,22 @@
+/** 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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,64 @@
+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);
+}