nylorun 0.0.0-bootstrap → 0.1.0-beta

package/dist/stack/paths.d.ts

@@ -0,0 +1,20 @@
+/** Files under the Host root that the stack commands read and write. */
+export interface StackPaths {
+    /** The Host root (`~/.nylorun` or `NYLORUN_HOME`), bind-mounted at /nylorun. */
+    root: string;
+    /** host.json: client-facing host and published port, no secrets. */
+    config: string;
+    /** host-credentials.json: the admin key, mode 0600. */
+    credentials: string;
+    /** host-state.json: written only by a launcher-managed Runtime. */
+    state: string;
+    tenants: string;
+    home: string;
+    tmp: string;
+    stack: string;
+    compose: string;
+    env: string;
+    /** Restate's request-identity private key (Ed25519 PKCS#8 PEM), mode 0600. */
+    restateIdentity: string;
+}
+export declare function stackPaths(hostRoot: string): StackPaths;

package/dist/stack/paths.js

@@ -0,0 +1,18 @@
+import { join, resolve } from "node:path";
+export function stackPaths(hostRoot) {
+    const root = resolve(hostRoot);
+    const stack = join(root, "stack");
+    return {
+        root,
+        config: join(root, "host.json"),
+        credentials: join(root, "host-credentials.json"),
+        state: join(root, "host-state.json"),
+        tenants: join(root, "tenants"),
+        home: join(root, "home"),
+        tmp: join(root, "tmp"),
+        stack,
+        compose: join(stack, "compose.yaml"),
+        env: join(stack, ".env"),
+        restateIdentity: join(stack, "restate-identity.pem"),
+    };
+}

package/dist/stack/ports.d.ts

@@ -0,0 +1,18 @@
+export declare const DEFAULT_PORTS: {
+    readonly runtime: 8787;
+    readonly studio: 4161;
+    readonly restate: 9070;
+};
+/** How the stack finds ports on 127.0.0.1; injectable for tests. */
+export interface PortProbe {
+    isFree(port: number): Promise<boolean>;
+    /** A port the OS reports free right now. */
+    pickFree(): Promise<number>;
+}
+export declare const loopbackPorts: PortProbe;
+/**
+ * Choose a port: the persisted one if any (kept even when busy, because the
+ * running stack may hold it), else the default when free, else a free one.
+ * Never returns a port in `taken`.
+ */
+export declare function choosePort(probe: PortProbe, preferred: number, persisted: number | undefined, taken: ReadonlySet<number>): Promise<number>;

package/dist/stack/ports.js

@@ -0,0 +1,45 @@
+import { createServer } from "node:net";
+export const DEFAULT_PORTS = {
+    runtime: 8787,
+    studio: 4161,
+    restate: 9070,
+};
+function listenOnce(port) {
+    const server = createServer();
+    return new Promise((resolve) => {
+        server.once("error", () => resolve(undefined));
+        server.listen({ port, host: "127.0.0.1", exclusive: true }, () => {
+            const address = server.address();
+            const bound = typeof address === "object" && address ? address.port : undefined;
+            server.close(() => resolve(bound));
+        });
+    });
+}
+export const loopbackPorts = {
+    async isFree(port) {
+        return (await listenOnce(port)) !== undefined;
+    },
+    async pickFree() {
+        const port = await listenOnce(0);
+        if (port === undefined)
+            throw new Error("Could not allocate a free loopback port.");
+        return port;
+    },
+};
+/**
+ * Choose a port: the persisted one if any (kept even when busy, because the
+ * running stack may hold it), else the default when free, else a free one.
+ * Never returns a port in `taken`.
+ */
+export async function choosePort(probe, preferred, persisted, taken) {
+    if (persisted !== undefined && !taken.has(persisted))
+        return persisted;
+    if (!taken.has(preferred) && (await probe.isFree(preferred)))
+        return preferred;
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        const port = await probe.pickFree();
+        if (!taken.has(port))
+            return port;
+    }
+    throw new Error("Could not allocate a free loopback port.");
+}

package/dist/stack/prepare.d.ts

@@ -0,0 +1,28 @@
+import { type StackEnv } from "./env-file.js";
+import { type HostConfigFile } from "./host-files.js";
+import type { StackImages } from "./images.js";
+import type { StackPaths } from "./paths.js";
+import { type PortProbe } from "./ports.js";
+export interface PreparedStack {
+    env: StackEnv;
+    host: HostConfigFile;
+    adminKey: string;
+    /** True when this run chose the ports (first start). */
+    firstRun: boolean;
+}
+/** Read the persisted stack settings without writing anything. */
+export declare function readStackEnv(paths: StackPaths): Promise<import("./env-file.js").PersistedStackEnv | undefined>;
+/**
+ * Write everything `docker compose up` needs under the Host root:
+ * host.json, host-credentials.json (0600), stack/compose.yaml,
+ * stack/.env (0600) and stack/restate-identity.pem (0600). Ports and the
+ * Postgres password persist in .env; the identity key persists in its PEM.
+ */
+export declare function prepareStack(input: {
+    paths: StackPaths;
+    images: StackImages;
+    uid: number;
+    gid: number;
+    runtimeVersion: string;
+    ports: PortProbe;
+}): Promise<PreparedStack>;

package/dist/stack/prepare.js

@@ -0,0 +1,65 @@
+import { randomBytes } from "node:crypto";
+import { chmod, readFile, rename, writeFile } from "node:fs/promises";
+import { renderComposeFile } from "./compose-file.js";
+import { parsePersisted, renderEnvFile } from "./env-file.js";
+import { ensureHostCredentials, ensureHostLayout, writeStackHostConfig, } from "./host-files.js";
+import { choosePort, DEFAULT_PORTS } from "./ports.js";
+import { ensureIdentityKey } from "./restate-identity.js";
+async function writeFileMode(path, text, mode) {
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    await writeFile(temporary, text, { mode });
+    await rename(temporary, path);
+    await chmod(path, mode);
+}
+async function readText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the persisted stack settings without writing anything. */
+export async function readStackEnv(paths) {
+    const text = await readText(paths.env);
+    return text === undefined ? undefined : parsePersisted(text);
+}
+/**
+ * Write everything `docker compose up` needs under the Host root:
+ * host.json, host-credentials.json (0600), stack/compose.yaml,
+ * stack/.env (0600) and stack/restate-identity.pem (0600). Ports and the
+ * Postgres password persist in .env; the identity key persists in its PEM.
+ */
+export async function prepareStack(input) {
+    const { paths } = input;
+    await ensureHostLayout(paths);
+    const persisted = (await readStackEnv(paths)) ?? {};
+    const firstRun = persisted.runtimePort === undefined;
+    const taken = new Set();
+    const runtimePort = await choosePort(input.ports, DEFAULT_PORTS.runtime, persisted.runtimePort, taken);
+    taken.add(runtimePort);
+    const studioPort = await choosePort(input.ports, DEFAULT_PORTS.studio, persisted.studioPort, taken);
+    taken.add(studioPort);
+    const restatePort = await choosePort(input.ports, DEFAULT_PORTS.restate, persisted.restatePort, taken);
+    const identity = await ensureIdentityKey(paths.restateIdentity, writeFileMode);
+    const env = {
+        runtimePort,
+        studioPort,
+        restatePort,
+        postgresPassword: persisted.postgresPassword ?? randomBytes(24).toString("hex"),
+        restateIdentityKey: identity.publicKey,
+        uid: input.uid,
+        gid: input.gid,
+        hostRoot: paths.root,
+        runtimeImage: input.images.runtime,
+        studioImage: input.images.studio,
+    };
+    const { adminKey } = await ensureHostCredentials(paths);
+    const host = await writeStackHostConfig(paths, {
+        port: runtimePort,
+        runtimeVersion: input.runtimeVersion,
+    });
+    await writeFileMode(paths.env, renderEnvFile(env), 0o600);
+    await writeFileMode(paths.compose, renderComposeFile(), 0o644);
+    return { env, host, adminKey, firstRun };
+}

package/dist/stack/restate-identity.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Restate request identity (Runtime Architecture §9.1, §12.3). Restate signs
+ * every request to the Worker endpoint with an Ed25519 private key; the
+ * Runtime accepts only requests that verify against the public key.
+ *
+ * - The private key is a PKCS#8 PEM at `stack/restate-identity.pem` (mode
+ *   0600), mounted read-only into the restate service as
+ *   `RESTATE_WORKER__INVOKER__REQUEST_IDENTITY_PRIVATE_KEY_PEM_FILE`.
+ * - The public key goes to the Runtime as `NYLORUN_RESTATE_IDENTITY_KEY`, in
+ *   Restate's format: `publickeyv1_` followed by the base58btc encoding of
+ *   the raw 32-byte public key. Restate logs the same string as the key id
+ *   (`kid`) when it loads the PEM.
+ */
+export declare const IDENTITY_KEY_PREFIX = "publickeyv1_";
+/** Base58 with the Bitcoin alphabet; each leading zero byte becomes "1". */
+export declare function base58btc(bytes: Uint8Array): string;
+/** The `publickeyv1_...` string for an Ed25519 private key PEM. */
+export declare function identityPublicKey(privateKeyPem: string): string;
+export declare function generateIdentityPem(): string;
+/**
+ * Read the identity PEM at `path`, creating it (mode 0600) on first start, and
+ * return its public key. An existing key is kept, so Restate's signatures stay
+ * valid across starts.
+ */
+export declare function ensureIdentityKey(path: string, write: (path: string, text: string, mode: number) => Promise<void>): Promise<{
+    publicKey: string;
+    created: boolean;
+}>;

package/dist/stack/restate-identity.js

@@ -0,0 +1,92 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync } from "node:crypto";
+import { chmod, readFile } from "node:fs/promises";
+import { CliError } from "../errors.js";
+/**
+ * Restate request identity (Runtime Architecture §9.1, §12.3). Restate signs
+ * every request to the Worker endpoint with an Ed25519 private key; the
+ * Runtime accepts only requests that verify against the public key.
+ *
+ * - The private key is a PKCS#8 PEM at `stack/restate-identity.pem` (mode
+ *   0600), mounted read-only into the restate service as
+ *   `RESTATE_WORKER__INVOKER__REQUEST_IDENTITY_PRIVATE_KEY_PEM_FILE`.
+ * - The public key goes to the Runtime as `NYLORUN_RESTATE_IDENTITY_KEY`, in
+ *   Restate's format: `publickeyv1_` followed by the base58btc encoding of
+ *   the raw 32-byte public key. Restate logs the same string as the key id
+ *   (`kid`) when it loads the PEM.
+ */
+export const IDENTITY_KEY_PREFIX = "publickeyv1_";
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+/** Base58 with the Bitcoin alphabet; each leading zero byte becomes "1". */
+export function base58btc(bytes) {
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros += 1;
+    // Little-endian base-58 digits of the big-endian number after the zeros.
+    const digits = [];
+    for (let index = zeros; index < bytes.length; index += 1) {
+        let carry = bytes[index];
+        for (let digit = 0; digit < digits.length; digit += 1) {
+            carry += digits[digit] * 256;
+            digits[digit] = carry % 58;
+            carry = Math.floor(carry / 58);
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = Math.floor(carry / 58);
+        }
+    }
+    let out = "1".repeat(zeros);
+    for (let digit = digits.length - 1; digit >= 0; digit -= 1)
+        out += BASE58_ALPHABET[digits[digit]];
+    return out;
+}
+/** The `publickeyv1_...` string for an Ed25519 private key PEM. */
+export function identityPublicKey(privateKeyPem) {
+    let jwk;
+    try {
+        const key = createPrivateKey(privateKeyPem);
+        if (key.asymmetricKeyType !== "ed25519")
+            throw new Error("not an Ed25519 key");
+        jwk = createPublicKey(key).export({ format: "jwk" });
+    }
+    catch (error) {
+        throw new CliError(`The Restate identity key is not an Ed25519 PKCS#8 PEM (${error instanceof Error ? error.message : String(error)})`, 1);
+    }
+    const raw = Buffer.from(jwk.x ?? "", "base64url");
+    if (raw.length !== 32)
+        throw new CliError("The Restate identity public key is not 32 bytes", 1);
+    return `${IDENTITY_KEY_PREFIX}${base58btc(raw)}`;
+}
+export function generateIdentityPem() {
+    const { privateKey } = generateKeyPairSync("ed25519");
+    return privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+}
+/**
+ * Read the identity PEM at `path`, creating it (mode 0600) on first start, and
+ * return its public key. An existing key is kept, so Restate's signatures stay
+ * valid across starts.
+ */
+export async function ensureIdentityKey(path, write) {
+    let pem;
+    try {
+        pem = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (pem !== undefined) {
+        let publicKey;
+        try {
+            publicKey = identityPublicKey(pem);
+        }
+        catch (error) {
+            throw new CliError(`${path}: ${error.message}. Delete it and run "nylorun start" to create a new one.`, 1);
+        }
+        await chmod(path, 0o600);
+        return { publicKey, created: false };
+    }
+    pem = generateIdentityPem();
+    await write(path, pem, 0o600);
+    return { publicKey: identityPublicKey(pem), created: true };
+}

package/dist/stack/studio-login.d.ts

@@ -0,0 +1,14 @@
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Studio's origin as the CLI opens it: always `localhost` (the cookie's host). */
+export declare function studioOrigin(port: number): string;
+/**
+ * Ask the Studio container for a single-use login token with the admin key
+ * (`POST /_studio/login-tokens`, Studio §6) and return the URL to open.
+ * Accepts `{ loginUrl }`, `{ url }` or `{ token }` in the response.
+ */
+export declare function mintStudioLogin(input: {
+    fetch: FetchLike;
+    studioPort: number;
+    adminKey: string;
+    timeoutMs?: number;
+}): Promise<string>;

package/dist/stack/studio-login.js

@@ -0,0 +1,37 @@
+import { STACK_CLIENT_HOST } from "./host-files.js";
+/** Studio's origin as the CLI opens it: always `localhost` (the cookie's host). */
+export function studioOrigin(port) {
+    return `http://${STACK_CLIENT_HOST}:${port}`;
+}
+/**
+ * Ask the Studio container for a single-use login token with the admin key
+ * (`POST /_studio/login-tokens`, Studio §6) and return the URL to open.
+ * Accepts `{ loginUrl }`, `{ url }` or `{ token }` in the response.
+ */
+export async function mintStudioLogin(input) {
+    const origin = studioOrigin(input.studioPort);
+    const response = await input.fetch(`${origin}/_studio/login-tokens`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${input.adminKey}`,
+            "content-type": "application/json",
+            accept: "application/json",
+        },
+        body: "{}",
+        redirect: "error",
+        signal: AbortSignal.timeout(input.timeoutMs ?? 5000),
+    });
+    if (!response.ok)
+        throw new Error(`Studio refused a login token (HTTP ${response.status}).`);
+    const body = (await response.json());
+    for (const field of ["loginUrl", "url"]) {
+        const value = body[field];
+        if (typeof value === "string" && value !== "") {
+            // A relative URL is resolved against the published origin.
+            return new URL(value, origin).toString();
+        }
+    }
+    if (typeof body.token === "string" && body.token !== "")
+        return `${origin}/login?token=${encodeURIComponent(body.token)}`;
+    throw new Error("Studio answered without a login token.");
+}

package/dist/stack/versions.d.ts

@@ -0,0 +1,9 @@
+/** An image this CLI release pins in `cli/package.json` `nylorun` (D7). */
+export type PinnedImage = "runtime" | "studio";
+/**
+ * The version this CLI release pins for an image, from `cli/package.json`
+ * `nylorun.runtime` or `nylorun.studio`: the tag of `ghcr.io/nylorun/<name>`
+ * the stack runs unless `NYLORUN_RUNTIME_IMAGE` / `NYLORUN_STUDIO_IMAGE`
+ * overrides it. The release tooling writes both pins.
+ */
+export declare function pinnedVersion(name: PinnedImage): string;

package/dist/stack/versions.js

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "../errors.js";
+function cliPackageJsonPath() {
+    // src/stack/*.ts and dist/stack/*.js both sit two levels below cli/.
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+}
+/**
+ * The version this CLI release pins for an image, from `cli/package.json`
+ * `nylorun.runtime` or `nylorun.studio`: the tag of `ghcr.io/nylorun/<name>`
+ * the stack runs unless `NYLORUN_RUNTIME_IMAGE` / `NYLORUN_STUDIO_IMAGE`
+ * overrides it. The release tooling writes both pins.
+ */
+export function pinnedVersion(name) {
+    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?.[name];
+    if (typeof version !== "string" || version.trim() === "") {
+        throw new CliError(`cli/package.json is missing "nylorun.${name}" (the pinned ${name} image version).`, 1);
+    }
+    return version;
+}

package/package.json

@@ -1,7 +1,47 @@
 {
   "name": "nylorun",
-  "version": "0.0.0-bootstrap",
-  "description": "Set up and run the local Nylorun stack. Placeholder; the first release is coming.",
+  "version": "0.1.0-beta",
+  "type": "module",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/nylorun/harness.git", "directory": "nylorun" }
+  "description": "Set up and run the local Nylorun stack (Runtime and Studio) with Docker Compose",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nylorun/harness.git",
+    "directory": "nylorun"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "npm run clean && node ../scripts/check-typescript-version.mjs && tsc -p tsconfig.json",
+    "clean": "node -e \"import('node:fs').then(({rmSync})=>rmSync('dist',{recursive:true,force:true}))\"",
+    "check": "npm run build && npm test && node scripts/check-package.mjs",
+    "test": "vitest run --passWithNoTests",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@nylorun/core": "0.6.0-beta"
+  },
+  "devDependencies": {
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "@types/node": "^26.5.0",
+    "vitest": "^5.0.1"
+  },
+  "bin": {
+    "nylorun": "dist/cli.js"
+  },
+  "nylorun": {
+    "runtime": "0.11.0-beta",
+    "studio": "0.10.0-beta"
+  }
 }