nylorun 0.2.1-beta → 0.4.0-beta

package/dist/stack/paths.js

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

package/dist/stack/ports.d.ts

@@ -1,5 +1,7 @@
 export declare const DEFAULT_PORTS: {
     readonly runtime: 8787;
+    /** The Runtime's operator listener (Admin API). */
+    readonly admin: 8788;
     readonly studio: 4161;
     readonly restate: 9070;
 };

package/dist/stack/ports.js

@@ -1,6 +1,8 @@
 import { createServer } from "node:net";
 export const DEFAULT_PORTS = {
     runtime: 8787,
+    /** The Runtime's operator listener (Admin API). */
+    admin: 8788,
     studio: 4161,
     restate: 9070,
 };

package/dist/stack/prepare.d.ts

@@ -11,18 +11,34 @@ export interface PreparedStack {
     firstRun: boolean;
 }
 /** Read the persisted stack settings without writing anything. */
-export declare function readStackEnv(paths: StackPaths): Promise<import("./env-file.js").PersistedStackEnv | undefined>;
+export declare function readStackEnv(paths: Pick<StackPaths, "env">): 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
+ * host.json, host-credentials.json (0600), docker/compose.yaml,
+ * docker/.env (0600) and docker/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;
+    /** The stack's name (its Tenant's name) and its Compose project. */
+    name: string;
+    project: string;
     images: StackImages;
     uid: number;
     gid: number;
-    runtimeVersion: string;
+    /** Recorded in host.json; undefined keeps the recorded version. */
+    runtimeVersion: string | undefined;
     ports: PortProbe;
+    /** Ports other stacks keep in their `.env`: never chosen for a port not chosen yet. */
+    reserved?: ReadonlySet<number>;
+    /** `NYLORUN_DERIVED_PRINCIPALS` from the environment of `nylorun start`; else kept. */
+    derivedPrincipals?: string;
+    /**
+     * Changes to the origins that may embed Studio: `reset` goes back to the
+     * defaults, `add` appends (for example a desktop app's dev server).
+     */
+    studioEmbedOrigins?: {
+        add?: readonly string[];
+        reset?: boolean;
+    };
 }): Promise<PreparedStack>;

package/dist/stack/prepare.js

@@ -1,8 +1,10 @@
 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 { parseFrameAncestors } from "@nylorun/core/contracts";
+import { CliError } from "../errors.js";
+import { DEFAULT_STUDIO_FRAME_ANCESTORS, parseDerivedPrincipals, parsePersisted, renderEnvFile, } from "./env-file.js";
+import { ensureHostCredentials, ensureVaultKey, 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) {
@@ -26,8 +28,8 @@ export async function readStackEnv(paths) {
 }
 /**
  * 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
+ * host.json, host-credentials.json (0600), docker/compose.yaml,
+ * docker/.env (0600) and docker/restate-identity.pem (0600). Ports and the
  * Postgres password persist in .env; the identity key persists in its PEM.
  */
 export async function prepareStack(input) {
@@ -36,30 +38,57 @@ export async function prepareStack(input) {
     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 reserved = input.reserved ?? new Set();
+    const pick = async (preferred, persistedPort) => {
+        const avoid = persistedPort === undefined ? new Set([...taken, ...reserved]) : taken;
+        const port = await choosePort(input.ports, preferred, persistedPort, avoid);
+        taken.add(port);
+        return port;
+    };
+    const runtimePort = await pick(DEFAULT_PORTS.runtime, persisted.runtimePort);
+    const adminPort = await pick(DEFAULT_PORTS.admin, persisted.adminPort);
+    const studioPort = await pick(DEFAULT_PORTS.studio, persisted.studioPort);
+    const restatePort = await pick(DEFAULT_PORTS.restate, persisted.restatePort);
     const identity = await ensureIdentityKey(paths.restateIdentity, writeFileMode);
+    let added;
+    try {
+        added = parseFrameAncestors((input.studioEmbedOrigins?.add ?? []).join(" "));
+    }
+    catch (error) {
+        throw new CliError(`--studio-embed-origin: ${error instanceof Error ? error.message : String(error)}`, 2);
+    }
+    const base = input.studioEmbedOrigins?.reset || persisted.studioFrameAncestors === undefined
+        ? [...DEFAULT_STUDIO_FRAME_ANCESTORS]
+        : persisted.studioFrameAncestors;
+    const studioFrameAncestors = [...new Set([...base, ...added])].join(" ");
     const env = {
         runtimePort,
+        adminPort,
         studioPort,
         restatePort,
         postgresPassword: persisted.postgresPassword ?? randomBytes(24).toString("hex"),
+        // Kept across starts: a new token would recreate the runtime and gateway containers.
+        gatesToken: persisted.gatesToken ?? randomBytes(32).toString("hex"),
         restateIdentityKey: identity.publicKey,
         uid: input.uid,
         gid: input.gid,
         hostRoot: paths.root,
         runtimeImage: input.images.runtime,
         studioImage: input.images.studio,
+        studioFrameAncestors,
+        stackName: input.name,
+        derivedPrincipals: (input.derivedPrincipals?.trim()
+            ? parseDerivedPrincipals(input.derivedPrincipals, "NYLORUN_DERIVED_PRINCIPALS")
+            : (persisted.derivedPrincipals ?? ["project"])).join(","),
     };
     const { adminKey } = await ensureHostCredentials(paths);
+    await ensureVaultKey(paths);
     const host = await writeStackHostConfig(paths, {
         port: runtimePort,
+        adminPort,
         runtimeVersion: input.runtimeVersion,
     });
     await writeFileMode(paths.env, renderEnvFile(env), 0o600);
-    await writeFileMode(paths.compose, renderComposeFile(), 0o644);
+    await writeFileMode(paths.compose, renderComposeFile(input.project), 0o644);
     return { env, host, adminKey, firstRun };
 }

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

@@ -3,7 +3,7 @@
  * 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
+ * - The private key is a PKCS#8 PEM at `docker/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

package/dist/stack/restate-identity.js

@@ -6,7 +6,7 @@ import { CliError } from "../errors.js";
  * 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
+ * - The private key is a PKCS#8 PEM at `docker/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

package/dist/stack/stacks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The machine's local stacks (tenancy.md §6): one installation per stack, each with its own
+ * Host root `~/.nylorun/stacks/<name>/`, Compose project `nylorun-<name>`, ports and volumes.
+ * `~/.nylorun` itself held the single stack of older releases (the legacy stack).
+ */
+/** A stack name: also part of its Compose project, so Compose's rules apply. */
+export declare const STACK_NAME: RegExp;
+/** `~/.nylorun`: the stacks, and the legacy stack's files. Tests pass another directory. */
+export declare function defaultNylorunRoot(): string;
+export declare function stacksDir(base: string): string;
+export declare function stackRoot(base: string, name: string): string;
+export declare function assertStackName(name: string, source: string): string;
+/** A directory name as a stack name: lowercased, other characters as `-`, trimmed. */
+export declare function sanitizeStackName(raw: string): string;
+/** `stack.json` in a Host root: the stack's name and the project it was created for. */
+export interface StackRecord {
+    format: 1;
+    name: string;
+    /** The project directory `nylorun start` created the stack in; absent outside a project. */
+    project?: string;
+}
+export declare function stackRecordPath(root: string): string;
+export declare function readStackRecord(root: string): Promise<StackRecord | undefined>;
+export declare function writeStackRecord(root: string, record: Omit<StackRecord, "format">): Promise<void>;
+export interface StackEntry {
+    name: string;
+    root: string;
+    record?: StackRecord;
+}
+/** The stacks under `<base>/stacks`, by name. */
+export declare function listStacks(base: string): Promise<StackEntry[]>;
+/**
+ * The stack name for a project without a link: the directory's name, or the first `-2`,
+ * `-3`, … suffix that no stack of another project directory holds. A stack this project
+ * directory created keeps its name.
+ */
+export declare function chooseStackName(base: string, projectDir: string): Promise<string>;
+/** The single stack of older releases: Compose project `nylorun`, Host root `~/.nylorun`. */
+export interface LegacyStack {
+    root: string;
+    project: "nylorun";
+    compose: string;
+    env: string;
+}
+export declare function legacyStack(base: string): LegacyStack | undefined;
+/** What `nylorun legacy delete` removes from `~/.nylorun`: the old layout only, never `stacks/`. */
+export declare const LEGACY_ENTRIES: readonly ["host.json", "host-credentials.json", "host-state.json", "stack", "tenants", "home", "tmp", "trash"];

package/dist/stack/stacks.js

@@ -0,0 +1,116 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { CliError } from "../errors.js";
+/**
+ * The machine's local stacks (tenancy.md §6): one installation per stack, each with its own
+ * Host root `~/.nylorun/stacks/<name>/`, Compose project `nylorun-<name>`, ports and volumes.
+ * `~/.nylorun` itself held the single stack of older releases (the legacy stack).
+ */
+/** A stack name: also part of its Compose project, so Compose's rules apply. */
+export const STACK_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/** `~/.nylorun`: the stacks, and the legacy stack's files. Tests pass another directory. */
+export function defaultNylorunRoot() {
+    return resolve(join(homedir(), ".nylorun"));
+}
+export function stacksDir(base) {
+    return join(base, "stacks");
+}
+export function stackRoot(base, name) {
+    return join(stacksDir(base), name);
+}
+export function assertStackName(name, source) {
+    if (!STACK_NAME.test(name))
+        throw new CliError(`${source} must be lowercase letters, digits, "-" or "_", starting with a letter or digit: ${name}`, 2);
+    return name;
+}
+/** A directory name as a stack name: lowercased, other characters as `-`, trimmed. */
+export function sanitizeStackName(raw) {
+    const name = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "");
+    return name === "" ? "stack" : name;
+}
+export function stackRecordPath(root) {
+    return join(root, "stack.json");
+}
+export async function readStackRecord(root) {
+    try {
+        const value = JSON.parse(await readFile(stackRecordPath(root), "utf8"));
+        if (typeof value?.name !== "string" || !STACK_NAME.test(value.name))
+            return undefined;
+        return {
+            format: 1,
+            name: value.name,
+            ...(typeof value.project === "string" ? { project: value.project } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeStackRecord(root, record) {
+    const path = stackRecordPath(root);
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    const body = { format: 1, name: record.name, ...(record.project ? { project: record.project } : {}) };
+    await writeFile(temporary, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+}
+/** The stacks under `<base>/stacks`, by name. */
+export async function listStacks(base) {
+    let entries;
+    try {
+        entries = await readdir(stacksDir(base), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const stacks = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !STACK_NAME.test(entry.name))
+            continue;
+        const root = stackRoot(base, entry.name);
+        const record = await readStackRecord(root);
+        stacks.push({ name: entry.name, root, ...(record ? { record } : {}) });
+    }
+    return stacks.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * The stack name for a project without a link: the directory's name, or the first `-2`,
+ * `-3`, … suffix that no stack of another project directory holds. A stack this project
+ * directory created keeps its name.
+ */
+export async function chooseStackName(base, projectDir) {
+    const name = sanitizeStackName(basename(projectDir));
+    const stacks = await listStacks(base);
+    const candidate = new RegExp(`^${name}(?:-[0-9]+)?$`);
+    const own = stacks.find((stack) => candidate.test(stack.name) && stack.record?.project === projectDir);
+    if (own)
+        return own.name;
+    for (let suffix = 1;; suffix += 1) {
+        const next = suffix === 1 ? name : `${name}-${suffix}`;
+        if (!existsSync(stackRoot(base, next)))
+            return next;
+    }
+}
+export function legacyStack(base) {
+    const compose = join(base, "stack", "compose.yaml");
+    if (!existsSync(compose))
+        return undefined;
+    return { root: base, project: "nylorun", compose, env: join(base, "stack", ".env") };
+}
+/** What `nylorun legacy delete` removes from `~/.nylorun`: the old layout only, never `stacks/`. */
+export const LEGACY_ENTRIES = [
+    "host.json",
+    "host-credentials.json",
+    "host-state.json",
+    "stack",
+    "tenants",
+    "home",
+    "tmp",
+    "trash",
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.2.1-beta",
+  "version": "0.4.0-beta",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Set up and run the local Nylorun stack (Runtime and Studio) with Docker Compose",
@@ -30,7 +30,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/core": "0.8.0-beta"
+    "@nylorun/core": "0.10.0-beta"
   },
   "devDependencies": {
     "typescript": "npm:@typescript/typescript6@^6.0.2",
@@ -41,7 +41,7 @@
     "nylorun": "dist/cli.js"
   },
   "nylorun": {
-    "runtime": "0.13.0-beta",
-    "studio": "0.13.0-beta"
+    "runtime": "0.15.0-beta",
+    "studio": "0.15.0-beta"
   }
 }