@nylorun/cli 0.2.1-beta → 0.3.0-beta

package/dist/runtime/ephemeral.d.ts

@@ -0,0 +1,37 @@
+import { createAdmin as defaultCreateAdmin } from "@nylorun/admin";
+import type { Admin } from "@nylorun/admin";
+import { type LauncherOptions } from "./launcher.js";
+export interface EphemeralOptions extends LauncherOptions {
+    /** Temporary Host root. Default: a new directory under os.tmpdir(). */
+    home?: string;
+    /** Tenant display name. Default: directory basename or "ephemeral". */
+    name?: string;
+    /** Injected Admin factory (tests). Default: `@nylorun/admin` createAdmin. */
+    createAdmin?: typeof defaultCreateAdmin;
+    /** Abort / cleanup signal (tests and SIGINT wiring). */
+    signal?: AbortSignal;
+}
+export interface EphemeralTenant {
+    id: string;
+    name: string;
+}
+export interface EphemeralRuntime {
+    home: string;
+    url: string;
+    hostId: string;
+    version: string;
+    tenant: EphemeralTenant;
+    applicationKey: string;
+    admin: Admin;
+    /** Stop the Host and delete the temporary home. */
+    close(): Promise<void>;
+}
+/**
+ * `nylorun dev --ephemeral` Host setup (D§12):
+ * temporary home, start Host on port 0, `createAdmin({ home })`, `createTenant`.
+ *
+ * Uses launcher `up --port 0` (detached Host) rather than foreground `run`, so
+ * the CLI can continue with Project setup / tsx watch and still `down` on exit.
+ * Semantically matches D§12: temporary home, free port, createTenant, cleanup.
+ */
+export declare function startEphemeral(options?: EphemeralOptions): Promise<EphemeralRuntime>;

package/dist/runtime/ephemeral.js

@@ -0,0 +1,84 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAdmin as defaultCreateAdmin } from "@nylorun/admin";
+import { CliError } from "../errors.js";
+import { launcher, throwOnLauncherFailure, } from "./launcher.js";
+/**
+ * `nylorun dev --ephemeral` Host setup (D§12):
+ * temporary home, start Host on port 0, `createAdmin({ home })`, `createTenant`.
+ *
+ * Uses launcher `up --port 0` (detached Host) rather than foreground `run`, so
+ * the CLI can continue with Project setup / tsx watch and still `down` on exit.
+ * Semantically matches D§12: temporary home, free port, createTenant, cleanup.
+ */
+export async function startEphemeral(options = {}) {
+    const home = options.home ??
+        (await mkdtemp(join(tmpdir(), "nylorun-ephemeral-")));
+    const createAdminFn = options.createAdmin ?? defaultCreateAdmin;
+    const env = options.env ?? process.env;
+    const handle = await launcher(home, { env });
+    const up = await handle.invoke(["up", "--port", "0"], { env });
+    throwOnLauncherFailure(up);
+    const result = up.result ?? {};
+    const url = typeof result.url === "string" ? result.url : undefined;
+    if (!url) {
+        throw new CliError(`Ephemeral Runtime Host started without a URL under ${home}.`, 7);
+    }
+    const ready = {
+        url,
+        hostId: typeof result.hostId === "string" ? result.hostId : "host_unknown",
+        version: typeof result.version === "string"
+            ? result.version
+            : handle.runtime.version,
+    };
+    const admin = createAdminFn({ home });
+    const name = options.name ??
+        home.split(/[/\\]/).filter(Boolean).pop() ??
+        "ephemeral";
+    const created = await admin.createTenant({ name });
+    const tenant = {
+        id: created.tenant.id,
+        name: created.tenant.name ?? name,
+    };
+    let closed = false;
+    let closing;
+    const close = async () => {
+        if (closing)
+            return closing;
+        closing = (async () => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                const down = await handle.invoke(["down", "--force"], { env });
+                if (down.exitCode !== 0)
+                    throwOnLauncherFailure(down);
+            }
+            catch {
+                /* best-effort stop */
+            }
+            await rm(home, { recursive: true, force: true }).catch(() => undefined);
+        })();
+        return closing;
+    };
+    if (options.signal) {
+        const onAbort = () => {
+            void close();
+        };
+        if (options.signal.aborted)
+            void close();
+        else
+            options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    return {
+        home,
+        url: ready.url,
+        hostId: ready.hostId,
+        version: ready.version,
+        tenant,
+        applicationKey: created.applicationKey,
+        admin,
+        close,
+    };
+}

package/dist/runtime/exit-codes.d.ts

@@ -0,0 +1,9 @@
+import type { ErrorCode } from "@nylorun/agents";
+/**
+ * Map launcher error codes (and a few Host states) to Tenants-era CLI exit codes.
+ * See cli/README.md exit code table.
+ */
+export declare const LAUNCHER_ERROR_EXIT_CODES: Record<string, number>;
+export declare function exitCodeForLauncherError(code: ErrorCode | string | undefined): number;
+/** `runtime status` when the Host is not running. */
+export declare function exitCodeForStatusState(state: string | undefined): number | undefined;

package/dist/runtime/exit-codes.js

@@ -0,0 +1,43 @@
+/**
+ * Map launcher error codes (and a few Host states) to Tenants-era CLI exit codes.
+ * See cli/README.md exit code table.
+ */
+export const LAUNCHER_ERROR_EXIT_CODES = {
+    foreign_port: 4,
+    host_start_failed: 7,
+    incompatible_host: 5,
+    protocol_unsupported: 5,
+    // Everything else falls through to 1.
+    platform_unsupported: 1,
+    launcher_failed: 1,
+    lock_timeout: 1,
+    host_unresponsive: 1,
+    host_schema_newer: 1,
+    host_format_newer: 1,
+    downgrade_refused: 1,
+    upgrade_failed: 1,
+    active_work: 1,
+    not_found: 1,
+    connection_missing: 1,
+    host_rejected: 1,
+    origin_rejected: 1,
+    unsupported_media_type: 1,
+    tenant_conflict: 1,
+};
+export function exitCodeForLauncherError(code) {
+    if (!code)
+        return 1;
+    return LAUNCHER_ERROR_EXIT_CODES[code] ?? 1;
+}
+/** `runtime status` when the Host is not running. */
+export function exitCodeForStatusState(state) {
+    if (state === "running")
+        return undefined;
+    if (state === "foreign-port")
+        return 4;
+    if (state === "stopped" || state === "absent")
+        return 3;
+    if (state === "unresponsive")
+        return 1;
+    return 3;
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,8 @@
+export { baselineEnv } from "./baseline.js";
+export { runtimeVersion } from "./version.js";
+export { findOnPath, launcher, runtimeInstallCommand, throwOnLauncherFailure, } from "./launcher.js";
+export type { InstalledRuntime, LauncherHandle, LauncherInvokeResult, LauncherJsonEvent, LauncherOptions, } from "./launcher.js";
+export { runtimeCommand, runtimeUsage } from "./commands.js";
+export { startEphemeral } from "./ephemeral.js";
+export type { EphemeralOptions, EphemeralRuntime, EphemeralTenant, } from "./ephemeral.js";
+export { LAUNCHER_ERROR_EXIT_CODES, exitCodeForLauncherError, exitCodeForStatusState, } from "./exit-codes.js";

package/dist/runtime/index.js

@@ -0,0 +1,6 @@
+export { baselineEnv } from "./baseline.js";
+export { runtimeVersion } from "./version.js";
+export { findOnPath, launcher, runtimeInstallCommand, throwOnLauncherFailure, } from "./launcher.js";
+export { runtimeCommand, runtimeUsage } from "./commands.js";
+export { startEphemeral } from "./ephemeral.js";
+export { LAUNCHER_ERROR_EXIT_CODES, exitCodeForLauncherError, exitCodeForStatusState, } from "./exit-codes.js";

package/dist/runtime/launcher.d.ts

@@ -0,0 +1,81 @@
+import { type ProgressEvent } from "./progress.js";
+/** The launcher command `@nylorun/runtime` installs (npm bin). */
+export declare const LAUNCHER_BIN = "nylorun-runtime";
+/** Resolve NYLORUN_HOME, an explicit home, or `~/.nylorun`. */
+export declare function resolveHome(home?: string): string;
+export type LauncherJsonEvent = ProgressEvent | {
+    type: "result";
+    [field: string]: unknown;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+    remedy: string;
+    details?: unknown;
+} | {
+    type: "log";
+    source: "host" | "tenant";
+    tenantId?: string;
+    line: string;
+};
+export interface LauncherInvokeResult {
+    events: LauncherJsonEvent[];
+    result?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+        remedy: string;
+        details?: unknown;
+    };
+    exitCode: number;
+    /** Raw stdout (NDJSON). */
+    stdout: string;
+    stderr: string;
+}
+/** The installed Runtime a handle runs, as its `version` command reports it. */
+export interface InstalledRuntime {
+    /** `nylorun-runtime` found on PATH. */
+    readonly bin: string;
+    readonly version: string;
+    /** Node the Runtime reported (the Host runs on the same Node). */
+    readonly node: string;
+}
+export interface LauncherHandle {
+    readonly home: string;
+    readonly runtime: InstalledRuntime;
+    /**
+     * Run a launcher command with `--json --home`. Progress events are rendered
+     * to stderr by default. Returns parsed events and the process exit code.
+     */
+    invoke(args: readonly string[], options?: InvokeOptions): Promise<LauncherInvokeResult>;
+    /**
+     * Long-running invoke (e.g. `run`, `logs --follow`). Resolves when the
+     * child exits; streams progress/log events as they arrive.
+     */
+    invokeStreaming(args: readonly string[], options?: InvokeOptions): Promise<LauncherInvokeResult>;
+}
+export interface InvokeOptions {
+    env?: NodeJS.ProcessEnv;
+    onEvent?: (event: LauncherJsonEvent) => void;
+    /** When false, skip default progress rendering. Default true. */
+    renderProgress?: boolean;
+    signal?: AbortSignal;
+}
+export interface LauncherOptions {
+    /** Environment for the launcher, including the PATH it is found on. */
+    env?: NodeJS.ProcessEnv;
+}
+/** Install command shown whenever the Runtime is missing or incompatible. */
+export declare function runtimeInstallCommand(): string;
+/** Find `name` on PATH (with PATHEXT on Windows). */
+export declare function findOnPath(name: string, env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Find the installed Runtime's launcher on PATH and check it speaks this CLI's
+ * launcher and Host protocols. Never downloads or installs anything: a missing
+ * Runtime is a prerequisite error that names the install command.
+ */
+export declare function launcher(home: string, options?: LauncherOptions): Promise<LauncherHandle>;
+/**
+ * Throw CliError with the Tenants-era exit code for a failed launcher invoke.
+ */
+export declare function throwOnLauncherFailure(outcome: LauncherInvokeResult): void;

package/dist/runtime/launcher.js

@@ -0,0 +1,243 @@
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { PROTOCOL_VERSION } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { exitCodeForLauncherError, } from "./exit-codes.js";
+import { renderProgress } from "./progress.js";
+import { runtimeVersion } from "./version.js";
+/** The launcher command `@nylorun/runtime` installs (npm bin). */
+export const LAUNCHER_BIN = "nylorun-runtime";
+/** The `nylorun-runtime --json` contract this CLI speaks (core LAUNCHER_PROTOCOL). */
+const LAUNCHER_PROTOCOL = 1;
+/** Resolve NYLORUN_HOME, an explicit home, or `~/.nylorun`. */
+export function resolveHome(home) {
+    if (home !== undefined && home.trim() !== "")
+        return resolve(home);
+    const fromEnv = process.env.NYLORUN_HOME?.trim();
+    if (fromEnv)
+        return resolve(fromEnv);
+    return resolve(join(homedir(), ".nylorun"));
+}
+/** Install command shown whenever the Runtime is missing or incompatible. */
+export function runtimeInstallCommand() {
+    return `npm install --global @nylorun/runtime@${runtimeVersion()}`;
+}
+/** Find `name` on PATH (with PATHEXT on Windows). */
+export function findOnPath(name, env) {
+    const dirs = (env.PATH ?? env.Path ?? "").split(delimiter).filter(Boolean);
+    const extensions = process.platform === "win32"
+        ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+        : [""];
+    for (const dir of dirs) {
+        for (const extension of extensions) {
+            const candidate = join(dir, `${name}${extension.toLowerCase()}`);
+            try {
+                if (statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch {
+                /* not here */
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * npm links a bin to the package's JS file: a symlink on POSIX, a `.cmd` shim
+ * next to the package on Windows. Running that file on this Node avoids
+ * spawning `.cmd` shims, which Node refuses without a shell.
+ */
+function launcherScript(bin) {
+    if (process.platform !== "win32") {
+        const real = realpathSync(bin);
+        return real.endsWith(".js") ? real : undefined;
+    }
+    const dir = dirname(bin);
+    const main = join("@nylorun", "runtime", "dist", "launcher", "main.js");
+    // Global prefix (`<prefix>/nylorun-runtime.cmd`) or project `.bin`.
+    for (const candidate of [
+        join(dir, "node_modules", main),
+        join(dir, "..", main),
+    ]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Find the installed Runtime's launcher on PATH and check it speaks this CLI's
+ * launcher and Host protocols. Never downloads or installs anything: a missing
+ * Runtime is a prerequisite error that names the install command.
+ */
+export async function launcher(home, options = {}) {
+    const resolvedHome = resolve(home);
+    const env = options.env ?? process.env;
+    const bin = findOnPath(LAUNCHER_BIN, env);
+    if (!bin) {
+        throw new CliError(`The Nylorun Runtime is not installed (no "${LAUNCHER_BIN}" on PATH).\nInstall it, then retry:\n  ${runtimeInstallCommand()}`, 1);
+    }
+    const probe = await invokeLauncher(bin, resolvedHome, ["version"], { env, renderProgress: false }, false);
+    throwOnLauncherFailure(probe);
+    const info = probe.result ?? {};
+    const version = typeof info.runtimeVersion === "string" ? info.runtimeVersion : "unknown";
+    const protocol = info.protocol;
+    const hostCompatible = typeof protocol?.min === "number" &&
+        typeof protocol.max === "number" &&
+        protocol.min <= PROTOCOL_VERSION &&
+        PROTOCOL_VERSION <= protocol.max;
+    if (info.launcherProtocol !== LAUNCHER_PROTOCOL || !hostCompatible) {
+        throw new CliError(`The installed Nylorun Runtime ${version} (${bin}) is not compatible with this CLI.\nInstall a compatible Runtime, then retry:\n  ${runtimeInstallCommand()}`, 1);
+    }
+    return createHandle(resolvedHome, {
+        bin,
+        version,
+        node: typeof info.node === "string" ? info.node : "unknown",
+    }, env);
+}
+function createHandle(home, runtime, defaultEnv) {
+    const run = (args, options = {}, streaming) => invokeLauncher(runtime.bin, home, args, {
+        ...options,
+        env: options.env ?? defaultEnv,
+    }, streaming);
+    return {
+        home,
+        runtime,
+        invoke: (args, options) => run(args, options, false),
+        invokeStreaming: (args, options) => run(args, options, true),
+    };
+}
+/** Quote one argument for cmd.exe (only used for non-npm `.cmd` shims). */
+function quoteForCmd(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+function spawnLauncher(bin, args, env) {
+    const options = {
+        env: { ...env },
+        stdio: ["ignore", "pipe", "pipe"],
+    };
+    const script = launcherScript(bin);
+    if (script)
+        return spawn(process.execPath, [script, ...args], options);
+    if (process.platform === "win32" && /\.(cmd|bat)$/i.test(bin)) {
+        // Windows runs .cmd files only through cmd.exe, which needs quoting.
+        return spawn(quoteForCmd(bin), args.map(quoteForCmd), {
+            ...options,
+            shell: true,
+        });
+    }
+    return spawn(bin, args, options);
+}
+async function invokeLauncher(bin, home, args, options, _streaming) {
+    const childArgs = ["--json", "--home", home, ...args];
+    const child = spawnLauncher(bin, childArgs, options.env);
+    const events = [];
+    let result;
+    let error;
+    let stdout = "";
+    let stderr = "";
+    let lineBuffer = "";
+    const handleLine = (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        events.push(event);
+        options.onEvent?.(event);
+        if (event.type === "progress" && options.renderProgress !== false) {
+            renderProgress(event);
+        }
+        if (event.type === "result") {
+            const { type: _t, ...fields } = event;
+            result = fields;
+        }
+        if (event.type === "error") {
+            error = {
+                code: event.code,
+                message: event.message,
+                remedy: event.remedy,
+                ...(event.details !== undefined ? { details: event.details } : {}),
+            };
+        }
+        if (event.type === "log") {
+            const prefix = event.source === "tenant" && event.tenantId
+                ? `[${event.tenantId}] `
+                : "";
+            process.stdout.write(`${prefix}${event.line}\n`);
+        }
+    };
+    child.stdout?.on("data", (chunk) => {
+        const text = chunk.toString("utf8");
+        stdout += text;
+        lineBuffer += text;
+        const parts = lineBuffer.split("\n");
+        lineBuffer = parts.pop() ?? "";
+        for (const part of parts)
+            handleLine(part);
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+    });
+    const abort = () => {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    if (options.signal) {
+        if (options.signal.aborted)
+            abort();
+        else
+            options.signal.addEventListener("abort", abort, { once: true });
+    }
+    const exitCode = await waitForExit(child);
+    if (lineBuffer.trim())
+        handleLine(lineBuffer);
+    if (options.signal) {
+        options.signal.removeEventListener("abort", abort);
+    }
+    return {
+        events,
+        ...(result ? { result } : {}),
+        ...(error ? { error } : {}),
+        exitCode,
+        stdout,
+        stderr,
+    };
+}
+function waitForExit(child) {
+    return new Promise((resolvePromise, reject) => {
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            if (code !== null)
+                resolvePromise(code);
+            else
+                resolvePromise(signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 1);
+        });
+    });
+}
+/**
+ * Throw CliError with the Tenants-era exit code for a failed launcher invoke.
+ */
+export function throwOnLauncherFailure(outcome) {
+    if (outcome.exitCode === 0)
+        return;
+    if (outcome.exitCode === 2) {
+        throw new CliError(outcome.error?.message ??
+            (outcome.stderr.trim() || "Invalid runtime arguments."), 2);
+    }
+    const code = outcome.error?.code;
+    const message = outcome.error
+        ? `${outcome.error.message}${outcome.error.remedy ? `\n${outcome.error.remedy}` : ""}`
+        : outcome.stderr.trim() || `Runtime launcher failed (exit ${outcome.exitCode}).`;
+    throw new CliError(message, exitCodeForLauncherError(code));
+}

package/dist/runtime/progress.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Render launcher progress the way the Tenants-era CLI did: phase name on
+ * stderr.
+ */
+export type ProgressEvent = {
+    type: "progress";
+    phase: "start" | "stop" | "wait";
+    message?: string;
+};
+export declare function renderProgress(event: ProgressEvent, write?: (line: string) => void): void;

package/dist/runtime/progress.js

@@ -0,0 +1,8 @@
+export function renderProgress(event, write = (line) => {
+    process.stderr.write(`${line}\n`);
+}) {
+    const parts = [event.phase];
+    if (event.message)
+        parts.push(event.message);
+    write(parts.join(" "));
+}

package/dist/runtime/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Recommended Runtime version from `cli/package.json` `nylorun.runtime` (D7):
+ * the version named in install instructions. Compatibility itself is checked
+ * by launcher and Host protocol, not by an exact match.
+ */
+export declare function runtimeVersion(): string;

package/dist/runtime/version.js

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "../errors.js";
+function cliPackageJsonPath() {
+    // src/runtime/*.ts and dist/runtime/*.js both sit two levels below cli/.
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+}
+/**
+ * Recommended Runtime version from `cli/package.json` `nylorun.runtime` (D7):
+ * the version named in install instructions. Compatibility itself is checked
+ * by launcher and Host protocol, not by an exact match.
+ */
+export function runtimeVersion() {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(cliPackageJsonPath(), "utf8"));
+    }
+    catch (error) {
+        throw new CliError(`Cannot read CLI package.json: ${error instanceof Error ? error.message : String(error)}`, 1);
+    }
+    const version = raw?.nylorun?.runtime;
+    if (typeof version !== "string" || version.trim() === "") {
+        throw new CliError('cli/package.json is missing "nylorun.runtime" (the recommended Runtime version).', 1);
+    }
+    return version;
+}

package/dist/tenant/commands.d.ts

@@ -0,0 +1,4 @@
+import { type AdminTenant } from "@nylorun/admin";
+/** Exact-and-unique name or id match. */
+export declare function matchTenant(tenants: readonly AdminTenant[], nameOrId: string): AdminTenant;
+export declare function tenantCommand(args: readonly string[]): Promise<void>;