nylorun 0.0.0-bootstrap → 0.1.1-beta

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# nylorun
+
+## 0.1.1-beta
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [a322696]
+- Updated dependencies [844bff3]
+- Updated dependencies [a322696]
+  - @nylorun/core@0.7.0-beta
+
+## 0.1.0-beta
+
+### Minor Changes
+
+- ba1b239: **`nylorun` sets up the local stack; `@nylorun/cli` becomes the Runtime client `nylo` (breaking beta).**
+
+  - New unscoped package **`nylorun`**: `npx nylorun up` sets up the Docker stack on the first run and starts it after that, from any directory; `npx nylorun down` stops it (volumes are kept). `up` and `down` are aliases of `start` and `stop`. It also owns `status`, `logs`, `studio`, `reset` and `doctor`, pins the Runtime and Studio images (`package.json` `nylorun.runtime` / `nylorun.studio`), depends on `@nylorun/core` only, and never creates Tenants.
+  - **`@nylorun/cli`** is the Runtime client with the command **`nylo`**: `nylo tenant create [name]` (creates the Tenant; in a project, writes the Project link and seeds the model provider and sandbox from `.env`), `nylo tenant current|list|use|status|reset|delete`, `nylo configure`, `nylo env` (was `nylorun status --env`) and `nylo doctor sandbox`. It no longer provides the `nylorun` command or the stack commands.
+  - **Removed:** `nylorun dev` and `nylorun dev --ephemeral`. Link once with `nylo tenant create`, then run the project's own `npm run dev`. Moved commands exit 2 and name their replacement.
+  - **Starter:** the generated project depends on `@nylorun/agents` only (no Nylorun devDependency); `dev` is `tsx watch --env-file-if-exists=.env src/main.ts`. `npm create @nylorun/agent` installs the project and prints the next steps (`npx nylorun up`, `npx @nylorun/cli tenant create`, `npm run dev`) instead of starting development; `--no-open` is accepted and ignored.
+  - `connectAgents` names those steps when it finds no Runtime connection. Runtime repair hints, model errors and core's sandbox message name `nylo` and `nylorun up`.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [bf1c2da]
+- Updated dependencies [ba1b239]
+- Updated dependencies [bf1c2da]
+- Updated dependencies [bf1c2da]
+- Updated dependencies [bf1c2da]
+  - @nylorun/core@0.6.0-beta

package/LICENSE

@@ -0,0 +1,192 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      Copyright 2026 Nylo
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

package/README.md

@@ -0,0 +1,98 @@
+# nylorun
+
+Sets up and runs the local Nylorun stack: the Runtime and Studio, as a Docker
+Compose stack. It needs nothing in your project; run it with `npx`:
+
+```sh
+npx nylorun up      # set up the stack on the first run, then start it
+npx nylorun down    # stop it; volumes (and Tenants) are kept
+```
+
+`nylorun` only manages the stack. It never creates Tenants: create one in
+Studio, or with the Runtime client, [`@nylorun/cli`](../cli/README.md) (command
+`nylo`), which also links a project to it. Depends on `@nylorun/core` only
+among Nylorun packages and never imports `@nylorun/runtime`. Vocabulary:
+[runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
+
+Prerequisites, installed by the developer (nylorun never downloads them): Node
+24 or newer, and Docker with Compose v2 ([Docker
+Desktop](https://www.docker.com/products/docker-desktop/),
+[OrbStack](https://orbstack.dev), [Colima](https://github.com/abiosoft/colima) or
+another engine). On Windows, install them inside
+[WSL2](https://learn.microsoft.com/windows/wsl/install); native Windows is not
+supported.
+
+```sh
+npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the stack's health
+```
+
+## Commands
+
+```sh
+nylorun up|start [--no-studio]     # set up (first run) and start the stack; print the Runtime URL and a Studio login URL
+nylorun down|stop                  # stop the containers; keep volumes
+nylorun status [--json]            # services, endpoints, Runtime health
+nylorun logs [service] [-f] [--tail <n>]   # postgres, restate, s2, runtime, studio
+nylorun studio [--no-open]         # fresh Studio login (on the linked Project's Tenant); starts the stack if needed
+nylorun reset [--yes]              # delete the stack's volumes and every Tenant
+nylorun doctor [--json]            # prerequisites and stack health
+```
+
+`up` and `down` are the Docker Compose spellings of `start` and `stop`: `down`
+stops the containers and keeps the volumes, so no Tenant data is lost.
+`nylorun stack <command>` still works as a hidden alias. Commands that act on a
+Tenant moved to the Runtime client and exit 2 naming the replacement:
+`nylorun dev`, `nylorun tenant …`, `nylorun configure`, `nylorun status --env`
+and `nylorun doctor sandbox`.
+
+## The stack
+
+`nylorun up` writes `compose.yaml` and `.env` (mode 0600) under
+`<Host root>/stack/` on the first run and reuses them after that. It runs the
+Compose project `nylorun` (override with `NYLORUN_STACK_PROJECT`): `postgres`,
+`restate`, `s2`, `runtime` and `studio`. The Runtime and Studio images are
+pinned by this release (`package.json` `nylorun.runtime` and `nylorun.studio`);
+`NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them (local builds,
+CI). Ports publish on loopback only: the Runtime on `8787`, Studio on `4161`
+and the Restate UI on `9070`, or free ports chosen on the first start and kept
+in `.env`. While the Host has no Tenant, `up` says how to create one.
+
+Studio has no password: nylorun asks the Studio container for a single-use
+login token with the admin key (`POST /_studio/login-tokens`) and opens
+`http://localhost:<port>/login?token=…`, which sets a session cookie. The
+token expires after two minutes; `nylorun studio` mints a fresh one. Inside a
+linked project, `nylorun studio` reads `.nylorun/link.json` (never writes it)
+and lands on that project's Tenant.
+
+## Host root
+
+The **Host root** is `NYLORUN_HOME` or `~/.nylorun`. It is bind-mounted into the
+Runtime and Studio containers, and holds `host.json` (the client-facing host
+and port), `host-credentials.json` (the admin key, mode 0600), the stack files
+and each Tenant's directory. Tenant data lives in the stack's Postgres, Restate
+and S2 volumes. The stack is one per machine: every project on it shares it,
+each with its own Tenant.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Generic failure, including a missing Docker or Compose v2 |
+| 2 | Usage error, or a removed or moved command |
+| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no stack yet |
+| 4 | The Runtime port is held by another Host |
+| 7 | The stack or Studio did not become ready |
+| 130 / 143 | SIGINT / SIGTERM |
+
+## Troubleshooting
+
+| Symptom | What to do |
+| --- | --- |
+| Docker missing or not running | Install or start Docker Desktop, OrbStack or Colima; `nylorun doctor` checks |
+| `426` from the Runtime | Upgrade nylorun (`npx nylorun@latest up`), or pin a matching older set |
+| Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `<Host root>/stack/.env` |
+| Logs | `nylorun logs runtime -f` |
+| Studio login expired | `nylorun studio` |
+
+See [MIGRATION.md](../MIGRATION.md).

package/dist/baseline.d.ts

@@ -0,0 +1,2 @@
+/** Frozen map captured when this module first loads. */
+export declare function baselineEnv(): Readonly<Record<string, string | undefined>>;

package/dist/baseline.js

@@ -0,0 +1,10 @@
+/**
+ * Snapshot of the process environment at CLI module load.
+ */
+const snapshot = Object.freeze({
+    ...process.env,
+});
+/** Frozen map captured when this module first loads. */
+export function baselineEnv() {
+    return snapshot;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./baseline.js";

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import "./baseline.js";
+import { baselineEnv } from "./baseline.js";
+import { CliError } from "./errors.js";
+import { linkedTenantId } from "./project/link.js";
+import { isStackCommand, stackCommand, stackUsage, studioCommand, tenantStudioPath, } from "./stack/index.js";
+const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|doctor>
+
+Local stack (Docker Compose):
+${stackUsage}
+  doctor [--json]                   check Node, Docker and Compose v2, and the stack's health
+
+nylorun sets up and runs the local stack. Tenants, Project links and model
+providers belong to the Runtime client: npx @nylorun/cli --help`;
+const CLIENT = "npx @nylorun/cli";
+/** Commands that moved to the Runtime client (`@nylorun/cli`, command `nylo`). */
+const MOVED_TO_CLIENT = {
+    dev: `nylorun dev was removed: run \`${CLIENT} tenant create\` once in your project, then your project's \`npm run dev\`.`,
+    tenant: `Tenant commands moved to the Runtime client: ${CLIENT} tenant …`,
+    configure: `nylorun configure moved to the Runtime client: ${CLIENT} configure`,
+    serve: "nylorun serve was removed. Use node dist/src/main.js with NYLORUN_RUNTIME_URL, NYLORUN_TENANT and NYLORUN_SERVER_KEY.",
+    runtime: "nylorun runtime was removed: the local Runtime runs in the Docker Compose stack. Use nylorun up|down|status|logs.",
+};
+const LOCAL_UI_REMOVED = "--local-ui was removed: Studio runs in the stack's studio container. Run nylorun studio.";
+const usageError = (message) => new CliError(message, 2);
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (!command || command === "--help" || command === "-h")
+        return void console.log(usage);
+    if (process.platform === "win32")
+        throw new CliError("Nylorun does not run on native Windows. Use WSL2: install Node 24 and Docker (Docker Desktop's WSL integration) inside your WSL distribution and run nylorun there (https://learn.microsoft.com/windows/wsl/install).", 1);
+    const moved = MOVED_TO_CLIENT[command];
+    if (moved)
+        throw usageError(moved);
+    if (command === "status" && args.includes("--env"))
+        throw usageError(`nylorun status --env moved to the Runtime client: ${CLIENT} env`);
+    if (command === "studio") {
+        if (args.includes("--local-ui"))
+            throw usageError(LOCAL_UI_REMOVED);
+        const tenantId = await linkedTenantId();
+        process.exitCode = await studioCommand(args, baselineEnv(), tenantId ? { next: tenantStudioPath(tenantId) } : {});
+        return;
+    }
+    if (isStackCommand(command)) {
+        process.exitCode = await stackCommand(command, args, baselineEnv());
+        return;
+    }
+    // `nylorun stack <command>`: the Wave 1 spelling, kept as a hidden alias.
+    if (command === "stack") {
+        const [name, ...rest] = args;
+        if (!isStackCommand(name))
+            throw usageError(usage);
+        process.exitCode = await stackCommand(name, rest, baselineEnv());
+        return;
+    }
+    if (command === "doctor") {
+        // `doctor stack` and `doctor runtime` are older spellings of `doctor`.
+        const options = args[0] === "stack" || args[0] === "runtime" ? args.slice(1) : args;
+        if (args[0] === "sandbox")
+            throw usageError(`nylorun doctor sandbox moved to the Runtime client: ${CLIENT} doctor sandbox`);
+        if (options.some((option) => option !== "--json"))
+            throw usageError("Usage: nylorun doctor [--json]");
+        const { doctorStack } = await import("./doctor.js");
+        process.exitCode = await doctorStack({ json: options.includes("--json"), env: baselineEnv() });
+        return;
+    }
+    throw usageError(usage);
+}
+async function finish(code) {
+    process.exitCode = code;
+    for (const stream of [process.stdout, process.stderr])
+        await new Promise((resolve) => stream.write("", () => resolve()));
+    process.exit(code);
+}
+void main().then(() => finish(process.exitCode === undefined ? 0 : Number(process.exitCode)), (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    return finish(error instanceof CliError ? error.exitCode : 1);
+});

package/dist/doctor.d.ts

@@ -0,0 +1,23 @@
+import { type Check, type StackDeps, type StackStatus } from "./stack/index.js";
+export interface StackDoctorReport {
+    node: {
+        version: string;
+        ok: boolean;
+    };
+    docker: Check;
+    compose?: Check;
+    stack?: Pick<StackStatus, "project" | "home" | "state" | "runtime" | "studio">;
+}
+/**
+ * `nylorun doctor`: check the prerequisites of the local stack (Node 24+,
+ * Docker, Compose v2) and, when they pass, the stack's health. Prints the fix
+ * for each problem and returns 1 when a prerequisite is missing or a running
+ * stack is unhealthy; installs and starts nothing.
+ */
+export declare function doctorStack(options: {
+    json: boolean;
+    env?: Readonly<Record<string, string | undefined>>;
+    /** Stack dependencies (tests). */
+    deps?: StackDeps;
+    log?: (line: string) => void;
+}): Promise<number>;

package/dist/doctor.js

@@ -0,0 +1,76 @@
+import { checkDocker, defaultStackDeps, readStackStatus, } from "./stack/index.js";
+/** Oldest Node the stack's tooling and the developer's application run on. */
+const MIN_NODE_MAJOR = 24;
+/**
+ * `nylorun doctor`: check the prerequisites of the local stack (Node 24+,
+ * Docker, Compose v2) and, when they pass, the stack's health. Prints the fix
+ * for each problem and returns 1 when a prerequisite is missing or a running
+ * stack is unhealthy; installs and starts nothing.
+ */
+export async function doctorStack(options) {
+    const log = options.log ?? ((line) => console.log(line));
+    const deps = options.deps ?? defaultStackDeps(options.env ?? process.env);
+    const nodeOk = Number(process.versions.node.split(".")[0]) >= MIN_NODE_MAJOR;
+    const checks = await checkDocker(deps.docker);
+    const report = {
+        node: { version: process.versions.node, ok: nodeOk },
+        ...checks,
+    };
+    if (checks.docker.ok && checks.compose?.ok) {
+        const status = await readStackStatus(deps);
+        report.stack = {
+            project: status.project,
+            home: status.home,
+            state: status.state,
+            runtime: status.runtime,
+            studio: status.studio,
+        };
+    }
+    const stackBroken = report.stack?.state === "running" && !report.stack.runtime.healthy;
+    const failed = !nodeOk || !checks.docker.ok || checks.compose?.ok === false || stackBroken;
+    if (options.json) {
+        log(JSON.stringify(report, null, 2));
+        return failed ? 1 : 0;
+    }
+    const line = (check) => check === undefined
+        ? "- not checked"
+        : check.ok
+            ? `✓ ${check.version}`
+            : `✗ ${check.problem}`;
+    const rows = [
+        [
+            "node",
+            nodeOk
+                ? `✓ ${process.versions.node}`
+                : `✗ ${process.versions.node}: install Node ${MIN_NODE_MAJOR} or newer`,
+        ],
+        ["docker", line(checks.docker)],
+        ["compose", line(checks.compose)],
+    ];
+    const stack = report.stack;
+    if (stack) {
+        rows.push([
+            "stack",
+            stack.state === "absent"
+                ? `- not created under ${stack.home}: run nylorun up`
+                : stack.state === "stopped"
+                    ? `- stopped (project ${stack.project}): run nylorun up`
+                    : stack.runtime.healthy
+                        ? `✓ running (project ${stack.project})`
+                        : `✗ running, but the Runtime does not answer: see nylorun status and nylorun logs runtime`,
+        ]);
+        if (stack.state === "running") {
+            rows.push([
+                "runtime",
+                stack.runtime.healthy
+                    ? `✓ ${stack.runtime.url ?? "?"} · ${stack.runtime.version ?? "?"}`
+                    : `✗ ${stack.runtime.url ?? "?"} not answering`,
+            ]);
+            rows.push(["studio", `${stack.studio.url ?? "?"} · ${stack.studio.state}`]);
+        }
+    }
+    const width = Math.max(...rows.map(([key]) => key.length)) + 2;
+    for (const [key, value] of rows)
+        log(`  ${key.padEnd(width)}${value}`);
+    return failed ? 1 : 0;
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+/** Exit codes are part of the CLI contract; see cli/README.md. */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+/** Exit codes are part of the CLI contract; see cli/README.md. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CliError";
+    }
+}

package/dist/home.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. The stack
+ * bind-mounts it into the Runtime and Studio containers, and `@nylorun/admin`
+ * reads `host.json` and the admin key from it.
+ */
+export declare function resolveHome(home?: string, env?: Readonly<Record<string, string | undefined>>): string;

package/dist/home.js

@@ -0,0 +1,15 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/**
+ * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. The stack
+ * bind-mounts it into the Runtime and Studio containers, and `@nylorun/admin`
+ * reads `host.json` and the admin key from it.
+ */
+export function resolveHome(home, env = process.env) {
+    if (home !== undefined && home.trim() !== "")
+        return resolve(home);
+    const fromEnv = env.NYLORUN_HOME?.trim();
+    if (fromEnv)
+        return resolve(fromEnv);
+    return resolve(join(homedir(), ".nylorun"));
+}

package/dist/project/link.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The linked Project's Tenant id, read from `.nylorun/link.json`, or undefined
+ * outside a linked Project. nylorun only reads the link: `@nylorun/cli` writes
+ * it when it creates or chooses a Tenant.
+ */
+export declare function linkedTenantId(cwd?: string): Promise<string | undefined>;

package/dist/project/link.js

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isTenantId } from "@nylorun/core/compatibility";
+import { findProjectRoot } from "./root.js";
+/**
+ * The linked Project's Tenant id, read from `.nylorun/link.json`, or undefined
+ * outside a linked Project. nylorun only reads the link: `@nylorun/cli` writes
+ * it when it creates or chooses a Tenant.
+ */
+export async function linkedTenantId(cwd = process.cwd()) {
+    const root = findProjectRoot(cwd);
+    if (!root)
+        return undefined;
+    try {
+        const link = JSON.parse(await readFile(join(root, ".nylorun", "link.json"), "utf8"));
+        return isTenantId(link.tenantId) ? link.tenantId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/project/root.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The nearest `.nylorun` wins so an initialised Project keeps working from a
+ * subdirectory; otherwise the nearest package.json defines the Project. The
+ * walk stops at the home directory because `~/.nylorun` is the Host root, never
+ * a Project root.
+ */
+export declare function findProjectRoot(cwd?: string): string | undefined;

package/dist/project/root.js

@@ -0,0 +1,44 @@
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+/**
+ * The nearest `.nylorun` wins so an initialised Project keeps working from a
+ * subdirectory; otherwise the nearest package.json defines the Project. The
+ * walk stops at the home directory because `~/.nylorun` is the Host root, never
+ * a Project root.
+ */
+export function findProjectRoot(cwd = process.cwd()) {
+    const stop = (() => {
+        try {
+            return realpathSync(homedir());
+        }
+        catch {
+            return homedir();
+        }
+    })();
+    let directory = resolve(cwd);
+    try {
+        directory = realpathSync(directory);
+    }
+    catch {
+        /* unresolvable cwd falls through */
+    }
+    const root = parse(directory).root;
+    let fallback;
+    for (;;) {
+        // The home directory is never a Project, but a package.json below it is.
+        if (directory === stop)
+            return fallback;
+        if (existsSync(join(directory, ".nylorun")))
+            return directory;
+        if (!fallback && existsSync(join(directory, "package.json")))
+            fallback = directory;
+        if (directory === root)
+            break;
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return fallback;
+}