nylorun 0.14.0-beta → 0.15.0-beta

package/dist/cli.js

@@ -3,88 +3,182 @@ import "./baseline.js";
 import { baselineEnv } from "./baseline.js";
 import { refuseNativeWindows, runCommand } from "./command.js";
 import { CliError } from "./errors.js";
-import { isStackCommand, keyCommand, keyUsage, mcpCommand, mcpUsage, sandboxCommand, sandboxUsage, stackCommand, stackUsage, studioCommand, } from "./stack/index.js";
-const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|sandbox|key|mcp|doctor|telemetry>
+import { defaultStackDeps, stackCommand, stackUsage, studioCommand } from "./stack/index.js";
+const usage = `nylorun <command>
 
-Local Tenants (Docker Compose), one per project:
+The installation:
 ${stackUsage}
-${sandboxUsage}
-${keyUsage}
-${mcpUsage}
   doctor [--json]                     check Node, Docker and Compose v2, and the Tenant's health
-  telemetry [status|enable|disable]   Studio's anonymous usage analytics (on unless disabled,
-                                      NYLORUN_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 or CI)
+  doctor sandbox [--tenant <name>] [--json]
+                                      the sandbox backend the Tenant's Host offers
+
+Groups, each with its own --help:
+  agents        list | get | save     the Tenant's agents (Runtime API, an application key)
+  sessions      list | create | get | send | approve | respond | cancel | watch | history
+                usage | calls | trace | exec
+                                      the Tenant's sessions (Runtime API)
+  environments  list | get | put | stop | reset | delete | snapshot | restore | versions
+                events | secrets      the Tenant's Environments (Runtime API)
+  artifacts     list | get | upload | download | tree | diff | zip | link | rm
+                                      the Tenant's file artifacts (Runtime API)
+  tenant        reset | keys | signing-keys | models | usage | calls | budgets | tool-policy |
+                settings | coverage | mcp
+                                      the Tenant's settings (Management API, a management key)
+  local         ls | delete | logs | reset | sandbox | telemetry
+                                      the Tenants on this machine (Docker and kubectl)
 
-A command acts on the Tenant --tenant or NYLORUN_TENANT names, else the linked project's,
-else (outside a project) the default Tenant; NYLORUN_HOME sets its Host root
-(default ~/.nylorun/tenants/<name>).
+A command acts on the local Tenant --tenant names, else the linked project's, else (outside a
+project) the default Tenant; NYLORUN_HOME sets its Host root (default
+~/.nylorun/tenants/<name>). Without --tenant, NYLORUN_RUNTIME_URL names a remote installation:
+with NYLORUN_MANAGEMENT_KEY for status, doctor sandbox and tenant; with NYLORUN_SERVER_KEY, or an
+identity provider's token in NYLORUN_TOKEN, for agents, sessions, environments and artifacts.
+The Runtime API groups act for a person with --as <subject> [--scope <scope>]...`;
+const localUsage = `nylorun local <command>
 
-nylorun sets up and runs local Tenants. "nylorun start" in a project creates the
-project's Tenant and the Project link; anywhere else, it starts the default Tenant.
-nylorun status and reset act on the local Tenant's containers and volumes on this machine.
-The package's other command, nylo, is the Runtime client of the linked installation: its
-status and reset go through the Management API, and it sets the model provider (nylo --help,
-or npx -p nylorun nylo --help).`;
-/** `nylo`, the Runtime client (this package's second command), run without installing. */
-const CLIENT = "npx -p nylorun nylo";
-/** Commands that were removed, or that are the Runtime client's (`nylo`). */
-const MOVED_TO_CLIENT = {
+The Tenants on this machine (Docker Compose), one per project:
+  ls [--json]                         the Tenants on this machine, with their memory in use
+  delete <tenant> --yes               remove a Tenant: containers, volumes and its Host root, with
+                                      the vault key (KEK)
+  logs [service] [--tenant <name>] [-f] [--tail <n>]
+                                      container logs
+  reset [--tenant <name>] [--yes]     delete the Tenant's data (volumes, tenant/ and vault key); the
+                                      next start creates it anew
+  sandbox enable | disable | status   run the Tenant's sandboxes as pods on a Kubernetes cluster
+                                      (nylorun local sandbox --help)
+  telemetry [status|enable|disable]   Studio's anonymous usage analytics (on unless disabled,
+                                      NYLORUN_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 or CI)`;
+/** Commands that moved into a group, or were removed. */
+const MOVED = {
+    logs: "nylorun logs moved: nylorun local logs",
+    ls: "nylorun ls moved: nylorun local ls",
+    delete: "nylorun delete moved: nylorun local delete",
+    telemetry: "nylorun telemetry moved: nylorun local telemetry",
+    reset: "nylorun reset moved: nylorun local reset deletes a local Tenant's volumes; nylorun tenant reset clears its sessions or Environments through the Management API",
+    key: "nylorun key moved: nylorun tenant keys put|list|rm",
+    keys: "nylorun keys is nylorun tenant keys put|list|rm",
+    mcp: "nylorun mcp moved: nylorun tenant mcp inspect <url>",
+    configure: "nylorun configure is nylorun tenant models set",
+    access: "nylorun access is nylorun tenant signing-keys list|rotate|revoke",
+    env: 'nylorun env was removed: the SDKs read the Project link themselves. For a process outside the project, give it a key of its own (nylorun tenant keys put <id>) and the Runtime URL "nylorun status" prints.',
     dev: "nylorun dev was removed: run `npx nylorun start` in your project (it creates the project's Tenant and the Project link), then your project's `npm run dev`.",
-    configure: `nylorun configure is the Runtime client's: ${CLIENT} configure`,
     serve: "nylorun serve was removed. Use node dist/src/main.js with NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEY.",
-    runtime: "nylorun runtime was removed: the local Runtime runs in Docker Compose. Use nylorun up|down|status|logs.",
+    runtime: "nylorun runtime was removed: the local Runtime runs in Docker Compose. Use nylorun up|down|status and nylorun local logs.",
+};
+const SANDBOX_MOVED = {
+    ls: "nylorun sandbox ls moved: nylorun environments list",
+    list: "nylorun sandbox ls moved: nylorun environments list",
+    rm: "nylorun sandbox rm moved: nylorun environments delete <id>",
+    delete: "nylorun sandbox rm moved: nylorun environments delete <id>",
 };
 const LOCAL_UI_REMOVED = "--local-ui was removed: Studio runs in its own container. Run nylorun studio.";
 const usageError = (message) => new CliError(message, 2);
+/** `nylorun local <command>`: the Docker and kubectl commands of this machine's Tenants. */
+async function local(args) {
+    const [command, ...rest] = args;
+    if (command === "--help" || command === "-h") {
+        console.log(localUsage);
+        return 0;
+    }
+    if (command === "ls" || command === "delete" || command === "logs" || command === "reset")
+        return stackCommand(command, rest, baselineEnv());
+    if (command === "sandbox") {
+        const [sub] = rest;
+        if (sub && SANDBOX_MOVED[sub])
+            throw usageError(SANDBOX_MOVED[sub]);
+        const { runSandboxCommand, sandboxUsage } = await import("./sandbox/commands.js");
+        if (sub === "--help" || sub === "-h") {
+            console.log(`nylorun local sandbox <enable|disable|status>\n\n${sandboxUsage}`);
+            return 0;
+        }
+        const { spawnKubectl } = await import("./sandbox/kubectl.js");
+        const deps = defaultStackDeps(baselineEnv());
+        return runSandboxCommand(rest, { stack: deps, kubectl: spawnKubectl(deps.env) });
+    }
+    if (command === "telemetry") {
+        const { telemetryCommand } = await import("./telemetry.js");
+        const { defaultNylorunRoot } = await import("./stack/stacks.js");
+        return telemetryCommand(rest, {
+            nylorunRoot: defaultNylorunRoot(),
+            env: baselineEnv(),
+            out: (line) => console.log(line),
+        });
+    }
+    throw usageError(command ? `Unknown local command ${command}.\n${localUsage}` : localUsage);
+}
 async function main() {
     const [command, ...args] = process.argv.slice(2);
     if (!command || command === "--help" || command === "-h")
         return void console.log(usage);
     refuseNativeWindows();
-    const moved = MOVED_TO_CLIENT[command];
+    if (command === "sandbox") {
+        const sub = args[0];
+        throw usageError((sub && SANDBOX_MOVED[sub]) ??
+            `nylorun sandbox moved: nylorun local sandbox ${sub && !sub.startsWith("-") ? sub : "enable|disable|status"}`);
+    }
+    const moved = MOVED[command];
     if (moved)
         throw usageError(moved);
     if (command === "status" && args.includes("--env"))
-        throw usageError(`nylorun status --env is the Runtime client's: ${CLIENT} env`);
+        throw usageError(MOVED.env);
+    const env = baselineEnv();
     if (command === "studio") {
         if (args.includes("--local-ui"))
             throw usageError(LOCAL_UI_REMOVED);
-        process.exitCode = await studioCommand(args, baselineEnv());
+        process.exitCode = await studioCommand(args, env);
         return;
     }
-    if (command === "sandbox") {
-        process.exitCode = await sandboxCommand(args, baselineEnv());
-        return;
+    if (command === "status" && !args.includes("--tenant")) {
+        // An installation the environment names answers through the Management API.
+        const { remoteConnection } = await import("./client/target.js");
+        if (remoteConnection(env, "management")) {
+            const { remoteStatus } = await import("./client/tenant.js");
+            process.exitCode = await remoteStatus(defaultStackDeps(env), args);
+            return;
+        }
     }
-    if (command === "key") {
-        process.exitCode = await keyCommand(args, baselineEnv());
+    if (["up", "start", "down", "stop", "status"].includes(command)) {
+        process.exitCode = await stackCommand(command, args, env);
         return;
     }
-    if (command === "mcp") {
-        process.exitCode = await mcpCommand(args, baselineEnv());
+    if (command === "local") {
+        process.exitCode = await local(args);
         return;
     }
-    if (isStackCommand(command)) {
-        process.exitCode = await stackCommand(command, args, baselineEnv());
+    if (command === "tenant") {
+        const { tenantCommand } = await import("./client/tenant.js");
+        process.exitCode = await tenantCommand(defaultStackDeps(env), args);
         return;
     }
-    if (command === "telemetry") {
-        const { telemetryCommand } = await import("./telemetry.js");
-        const { defaultNylorunRoot } = await import("./stack/stacks.js");
-        process.exitCode = await telemetryCommand(args, {
-            nylorunRoot: defaultNylorunRoot(),
-            env: baselineEnv(),
-            out: (line) => console.log(line),
-        });
+    if (command === "agents" || command === "sessions" || command === "environments" || command === "artifacts") {
+        const group = {
+            agents: async () => (await import("./client/agents.js")).agentsCommand,
+            sessions: async () => (await import("./client/sessions.js")).sessionsCommand,
+            environments: async () => (await import("./client/environments.js")).environmentsCommand,
+            artifacts: async () => (await import("./client/artifacts.js")).artifactsCommand,
+        }[command];
+        process.exitCode = await (await group())(defaultStackDeps(env), args);
         return;
     }
     if (command === "doctor") {
-        if (args[0] === "sandbox")
-            throw usageError(`nylorun doctor sandbox is the Runtime client's: ${CLIENT} doctor sandbox`);
+        const [topic, ...options] = args;
+        if (topic === "sandbox") {
+            const usage = "Usage: nylorun doctor sandbox [--tenant <name>] [--json]";
+            const tenantAt = options.indexOf("--tenant");
+            const tenant = tenantAt < 0 ? undefined : options[tenantAt + 1];
+            const rest = options.filter((_, index) => index !== tenantAt && index !== tenantAt + 1);
+            if ((tenantAt >= 0 && (!tenant || tenant.startsWith("-"))) || rest.some((option) => option !== "--json"))
+                throw usageError(usage);
+            const { doctorSandbox } = await import("./client/doctor.js");
+            await doctorSandbox(defaultStackDeps(env), {
+                json: rest.includes("--json"),
+                ...(tenant ? { tenant } : {}),
+            });
+            return;
+        }
         if (args.some((option) => option !== "--json"))
-            throw usageError("Usage: nylorun doctor [--json]");
+            throw usageError("Usage: nylorun doctor [--json] | nylorun doctor sandbox [--tenant <name>] [--json]");
         const { doctorStack } = await import("./doctor.js");
-        process.exitCode = await doctorStack({ json: args.includes("--json"), env: baselineEnv() });
+        process.exitCode = await doctorStack({ json: args.includes("--json"), env });
         return;
     }
     throw usageError(usage);

package/dist/client/agents.d.ts

@@ -0,0 +1,6 @@
+import type { StackDeps } from "../stack/commands.js";
+export declare const agentsUsage: string;
+/** Every `sha256:<hex>` a manifest names under a `files` map, with where it names it. */
+export declare function namedFiles(manifest: unknown): Map<string, string>;
+/** `nylorun agents <list|get|save> ...` */
+export declare function agentsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/agents.js

@@ -0,0 +1,148 @@
+/**
+ * `nylorun agents`: the Tenant's saved agents (`/v1/agents`, Runtime API). `save` takes a manifest
+ * and the folders that hold its files: a manifest names each definition file by the SHA-256 of
+ * its bytes (a skill's `files`), so the files are matched by content, whatever their paths.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { definitionFileHash } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { parseFlags, positional, printJson, printTable, readJson, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError, } from "./runtime.js";
+export const agentsUsage = `nylorun agents <list|get|save>
+
+The Tenant's saved agents, through the Runtime API with an application key (or NYLORUN_TOKEN).
+
+  list [--json]                       id, kind and description of each agent
+  get <id>                            the agent's manifest, as JSON
+  save <manifest.json|-> [--files <dir>]... [--implementation-version <v>] [--dry-run]
+                                      save the agent the manifest describes, first uploading the
+                                      definition files it names from the folders given (found by
+                                      their SHA-256, whatever their paths); --dry-run checks it
+                                      and saves nothing
+
+${runtimeFlagsUsage}`;
+const HASH = /^sha256:[0-9a-f]{64}$/;
+/** Every `sha256:<hex>` a manifest names under a `files` map, with where it names it. */
+export function namedFiles(manifest) {
+    const named = new Map();
+    const walk = (value, path) => {
+        if (!value || typeof value !== "object")
+            return;
+        if (Array.isArray(value))
+            return value.forEach((item, index) => walk(item, `${path}[${index}]`));
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "files" && child && typeof child === "object" && !Array.isArray(child)) {
+                for (const [file, hash] of Object.entries(child))
+                    if (typeof hash === "string" && HASH.test(hash) && !named.has(hash))
+                        named.set(hash, `${path}.files["${file}"]`);
+            }
+            else
+                walk(child, `${path}.${key}`);
+        }
+    };
+    walk(manifest, "manifest");
+    return named;
+}
+/** The files under `dirs`, by their hash. */
+async function filesByHash(dirs) {
+    const found = new Map();
+    const visit = async (dir) => {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                await visit(path);
+            else if (entry.isFile())
+                found.set(await definitionFileHash(new Uint8Array(await readFile(path))), path);
+        }
+    };
+    for (const dir of dirs) {
+        try {
+            await visit(dir);
+        }
+        catch (error) {
+            throw new CliError(`Cannot read --files ${dir}: ${error.message}`, 1);
+        }
+    }
+    return found;
+}
+async function list(deps, args) {
+    const usage = "nylorun agents list [--json]";
+    const flags = parseFlags(args, { booleans: ["--json"] }, usage);
+    positional(flags, 0, usage);
+    const { client } = await runtimeClient(deps, flags);
+    const { agents } = await runtimeCall(() => client.listAgents());
+    if (flags.booleans.has("--json")) {
+        printJson(deps, agents);
+        return 0;
+    }
+    if (agents.length === 0) {
+        deps.out("No agents saved.");
+        return 0;
+    }
+    printTable(deps, [
+        ["ID", "KIND", "DESCRIPTION"],
+        ...agents.map((agent) => {
+            const manifest = "manifest" in agent ? agent.manifest : undefined;
+            const description = ("description" in agent ? agent.description : undefined) ?? manifest?.description;
+            return [agent.agentId, manifest?.kind ?? "agent", description ?? "-"];
+        }),
+    ]);
+    return 0;
+}
+async function get(deps, args) {
+    const usage = "nylorun agents get <id>";
+    const flags = parseFlags(args, {}, usage);
+    const [id] = positional(flags, 1, usage);
+    const { client, connection } = await runtimeClient(deps, flags);
+    const { agents } = await runtimeCall(() => client.listAgents());
+    const agent = agents.find((item) => item.agentId === id);
+    if (!agent) {
+        deps.err(`No agent ${id} on ${connection.label}.`);
+        return 1;
+    }
+    printJson(deps, agent);
+    return 0;
+}
+async function save(deps, args) {
+    const usage = "nylorun agents save <manifest.json|-> [--files <dir>]... [--implementation-version <v>] [--dry-run]";
+    const flags = parseFlags(args, { booleans: ["--dry-run"], values: ["--implementation-version"], lists: ["--files"] }, usage);
+    const dryRun = flags.booleans.has("--dry-run");
+    const [path] = positional(flags, 1, usage);
+    const manifest = await readJson(path, "The manifest");
+    if (typeof manifest.id !== "string" || manifest.id === "")
+        throw usageError("The manifest has no id.");
+    const named = namedFiles(manifest);
+    const found = named.size === 0 ? new Map() : await filesByHash(flags.lists.get("--files") ?? []);
+    const missing = [...named].filter(([hash]) => !found.has(hash));
+    if (missing.length > 0)
+        throw new CliError(`The manifest names ${missing.length} ${missing.length === 1 ? "file" : "files"} not found under ${flags.lists.get("--files")?.join(", ") || "any --files folder"}:\n${missing.map(([hash, where]) => `  ${where} = ${hash}`).join("\n")}`, 1);
+    const { client, connection } = await runtimeClient(deps, flags);
+    let uploaded = 0;
+    for (const hash of named.keys()) {
+        if (await runtimeCall(() => client.files.has(hash)))
+            continue;
+        const bytes = new Uint8Array(await readFile(found.get(hash)));
+        await runtimeCall(() => client.files.upload(bytes, { sha256: hash }));
+        uploaded += 1;
+    }
+    const version = flags.values.get("--implementation-version");
+    const saved = await runtimeCall(() => client.saveAgent({ id: manifest.id, manifest: manifest }, { ...(version === undefined ? {} : { implementationVersion: version }), ...(dryRun ? { dryRun } : {}) }));
+    deps.err(`${dryRun ? "Checked (and saved nothing of)" : "Saved"} agent ${manifest.id} on ${connection.label}${named.size ? ` (${named.size} files, ${uploaded} uploaded)` : ""}.`);
+    printJson(deps, saved);
+    return 0;
+}
+/** `nylorun agents <list|get|save> ...` */
+export async function agentsCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "--help" || sub === "-h") {
+        deps.out(agentsUsage);
+        return 0;
+    }
+    if (sub === "list" || sub === "ls")
+        return list(deps, rest);
+    if (sub === "get")
+        return get(deps, rest);
+    if (sub === "save")
+        return save(deps, rest);
+    throw usageError(sub ? `Unknown agents command ${sub}.\n${agentsUsage}` : agentsUsage);
+}

package/dist/client/artifacts.d.ts

@@ -0,0 +1,4 @@
+import type { StackDeps } from "../stack/commands.js";
+export declare const artifactsUsage: string;
+/** `nylorun artifacts <command> ...` */
+export declare function artifactsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/artifacts.js

@@ -0,0 +1,210 @@
+/**
+ * `nylorun artifacts`: the Tenant's file artifacts (`/v1/artifacts`, Runtime API): upload a file
+ * (to name in a message with `sessions send --file`), list, download, browse a folder artifact
+ * (an Environment's disk), share a version with a capability link, and delete.
+ */
+import { createWriteStream } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { integerFlag, labelsOf, parseFlags, positional, printCursor, printJson, printTable, readStdin, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError, } from "./runtime.js";
+export const artifactsUsage = `nylorun artifacts <command>
+
+The Tenant's file artifacts, through the Runtime API with an application key (or NYLORUN_TOKEN).
+
+  list [--session <id>] [--label <key=value>]... [--limit <n>] [--cursor <c>] [--json]
+                                      newest first: id, kind, name, latest version, owner
+  get <id>                            the artifact and its versions, as JSON
+  upload <file|-> [--name <name>] [--content-type <type>] [--session <id>] [--label <key=value>]...
+                                      upload a file as a new artifact (--to <id>: as its next
+                                      version); prints its id
+  download <id> [--version <n>] [--output <file>]
+                                      the bytes, to a file or standard output
+  tree <id> [--version <n>]           a folder artifact's files
+  diff <id> [--version <n>] [--from <n>]
+                                      what changed between two versions of a folder
+  zip <id> [--version <n>] --output <file>
+                                      a folder artifact as a zip
+  link <id> [--version <n>] [--expires-in <s>] [--file <path>]
+                                      a capability link anyone holding it may download
+  rm <id>                             delete the artifact and its versions
+
+${runtimeFlagsUsage}`;
+async function list(deps, args) {
+    const usage = "nylorun artifacts list [--session <id>] [--label <key=value>]... [--limit <n>] [--cursor <c>] [--json]";
+    const flags = parseFlags(args, { booleans: ["--json"], values: ["--session", "--limit", "--cursor"], lists: ["--label"] }, usage);
+    positional(flags, 0, usage);
+    const sessionId = flags.values.get("--session");
+    const cursor = flags.values.get("--cursor");
+    const limit = integerFlag(flags, "--limit");
+    const labels = labelsOf(flags);
+    const { client } = await runtimeClient(deps, flags);
+    const page = await runtimeCall(() => client.artifacts.page({
+        ...(sessionId ? { sessionId } : {}),
+        ...(labels ? { labels } : {}),
+        ...(limit === undefined ? {} : { limit }),
+        ...(cursor ? { cursor } : {}),
+    }));
+    if (flags.booleans.has("--json")) {
+        printJson(deps, page);
+        return 0;
+    }
+    if (page.artifacts.length === 0)
+        deps.out("No artifacts.");
+    else
+        printTable(deps, [
+            ["ID", "KIND", "NAME", "VERSION", "OWNER"],
+            ...page.artifacts.map((item) => [
+                item.artifactId,
+                item.kind,
+                item.name,
+                String(item.latestVersion),
+                item.sessionId
+                    ? `session ${item.sessionId}`
+                    : item.environmentId
+                        ? `environment ${item.environmentId}`
+                        : "tenant",
+            ]),
+        ]);
+    printCursor(deps, page.nextCursor);
+    return 0;
+}
+async function get(deps, args) {
+    const usage = "nylorun artifacts get <id>";
+    const flags = parseFlags(args, {}, usage);
+    const [id] = positional(flags, 1, usage);
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.artifacts.get(id)));
+    return 0;
+}
+async function upload(deps, args) {
+    const usage = "nylorun artifacts upload <file|-> [--name <name>] [--content-type <type>] [--session <id>] [--label <key=value>]... [--to <id>]";
+    const flags = parseFlags(args, { values: ["--name", "--content-type", "--session", "--to"], lists: ["--label"] }, usage);
+    const [path] = positional(flags, 1, usage);
+    const to = flags.values.get("--to");
+    const name = flags.values.get("--name") ?? (path === "-" ? undefined : basename(path));
+    if (!to && !name)
+        throw usageError("Name the file with --name when it comes from standard input.");
+    if (to && (flags.values.has("--name") || flags.values.has("--session") || flags.lists.has("--label")))
+        throw usageError("--to uploads a version: --name, --session and --label belong to the artifact.");
+    const bytes = new Uint8Array(path === "-" ? await readStdin() : await readFile(path));
+    const contentType = flags.values.get("--content-type");
+    const sessionId = flags.values.get("--session");
+    const labels = labelsOf(flags);
+    const { client } = await runtimeClient(deps, flags);
+    const uploaded = await runtimeCall(() => to
+        ? client.artifacts.uploadVersion(to, bytes, contentType ? { contentType } : {})
+        : client.artifacts.upload(bytes, {
+            name: name,
+            ...(contentType ? { contentType } : {}),
+            ...(sessionId ? { sessionId } : {}),
+            ...(labels ? { labels } : {}),
+        }));
+    deps.err(`Uploaded ${uploaded.artifact.name}: version ${uploaded.version.version} of artifact ${uploaded.artifact.artifactId}.`);
+    deps.out(uploaded.artifact.artifactId);
+    return 0;
+}
+/** Writes `response`'s body to `output`, or to standard output. */
+async function save(response, output) {
+    if (!response.body)
+        return;
+    const source = Readable.fromWeb(response.body);
+    await pipeline(source, output === undefined ? process.stdout : createWriteStream(output));
+}
+async function download(deps, args) {
+    const usage = "nylorun artifacts download <id> [--version <n>] [--output <file>]";
+    const flags = parseFlags(args, { values: ["--version", "--output"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const version = integerFlag(flags, "--version");
+    const { client } = await runtimeClient(deps, flags);
+    const response = await runtimeCall(() => client.artifacts.download(id, version === undefined ? {} : { version }));
+    await save(response, flags.values.get("--output"));
+    return 0;
+}
+async function tree(deps, args) {
+    const usage = "nylorun artifacts tree <id> [--version <n>]";
+    const flags = parseFlags(args, { values: ["--version"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const version = integerFlag(flags, "--version");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.artifacts.tree(id, version === undefined ? {} : { version })));
+    return 0;
+}
+async function diff(deps, args) {
+    const usage = "nylorun artifacts diff <id> [--version <n>] [--from <n>]";
+    const flags = parseFlags(args, { values: ["--version", "--from"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const version = integerFlag(flags, "--version");
+    const from = integerFlag(flags, "--from");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.artifacts.diff(id, {
+        ...(version === undefined ? {} : { version }),
+        ...(from === undefined ? {} : { from }),
+    })));
+    return 0;
+}
+async function zip(deps, args) {
+    const usage = "nylorun artifacts zip <id> [--version <n>] --output <file>";
+    const flags = parseFlags(args, { values: ["--version", "--output"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const output = flags.values.get("--output");
+    if (!output)
+        throw usageError(`Usage: ${usage}`);
+    const version = integerFlag(flags, "--version");
+    const { client } = await runtimeClient(deps, flags);
+    const response = await runtimeCall(() => client.artifacts.zip(id, version === undefined ? {} : { version }));
+    await save(response, output);
+    return 0;
+}
+async function link(deps, args) {
+    const usage = "nylorun artifacts link <id> [--version <n>] [--expires-in <s>] [--file <path>]";
+    const flags = parseFlags(args, { values: ["--version", "--expires-in", "--file"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const version = integerFlag(flags, "--version");
+    const expiresIn = integerFlag(flags, "--expires-in");
+    const file = flags.values.get("--file");
+    const { client } = await runtimeClient(deps, flags);
+    const created = await runtimeCall(() => client.artifacts.link(id, {
+        ...(version === undefined ? {} : { version }),
+        ...(expiresIn === undefined ? {} : { expiresIn }),
+        ...(file ? { file } : {}),
+    }));
+    deps.err(JSON.stringify(created));
+    deps.out(created.url);
+    return 0;
+}
+async function rm(deps, args) {
+    const usage = "nylorun artifacts rm <id>";
+    const flags = parseFlags(args, {}, usage);
+    const [id] = positional(flags, 1, usage);
+    const { client } = await runtimeClient(deps, flags);
+    await runtimeCall(() => client.artifacts.delete(id));
+    deps.out(`Deleted artifact ${id}.`);
+    return 0;
+}
+const COMMANDS = {
+    list,
+    ls: list,
+    get,
+    upload,
+    download,
+    tree,
+    diff,
+    zip,
+    link,
+    rm,
+    delete: rm,
+};
+/** `nylorun artifacts <command> ...` */
+export async function artifactsCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "--help" || sub === "-h") {
+        deps.out(artifactsUsage);
+        return 0;
+    }
+    const command = sub !== undefined && Object.hasOwn(COMMANDS, sub) ? COMMANDS[sub] : undefined;
+    if (!command)
+        throw usageError(sub ? `Unknown artifacts command ${sub}.\n${artifactsUsage}` : artifactsUsage);
+    return command(deps, rest);
+}

package/dist/client/doctor.d.ts

@@ -1,3 +1,4 @@
+import type { StackDeps } from "../stack/commands.js";
 export type SandboxReport = {
     preference: string;
     backend: string | null;
@@ -20,7 +21,11 @@ export type SandboxReport = {
         };
     };
 };
-/** `nylo doctor sandbox`: Tenant sandbox report via the Management API (F2-4). */
-export declare function doctorSandbox(options: {
+/**
+ * `nylorun doctor sandbox`: the Tenant's sandbox report (`GET /v1/tenant/sandbox`, Management API)
+ * of the installation `target.ts` picks (F2-4).
+ */
+export declare function doctorSandbox(deps: StackDeps, options: {
     json: boolean;
+    tenant?: string;
 }): Promise<void>;