nylorun 0.13.0-beta → 0.15.0-beta

package/dist/client/doctor.js

@@ -1,7 +1,6 @@
 import { release } from "node:os";
-import { findProjectRoot } from "@nylorun/core/project";
 import { CliError } from "../errors.js";
-import { linkedConnection, managementClient } from "./project/connection.js";
+import { connect, managementClient } from "./target.js";
 function platformLine() {
     const os = process.platform === "darwin"
         ? "macOS"
@@ -10,24 +9,26 @@ function platformLine() {
             : process.platform;
     return `${os} (kernel ${release()}) · ${process.arch}`;
 }
-/** The Tenant's sandbox report (`GET /v1/tenant/sandbox`, Management API). */
-async function fetchSandboxReport() {
-    const connection = await linkedConnection(findProjectRoot() ?? process.cwd());
-    return (await managementClient(connection).settings.sandbox.get());
-}
-/** `nylo doctor sandbox`: Tenant sandbox report via the Management API (F2-4). */
-export async 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 async function doctorSandbox(deps, options) {
+    const log = (line) => deps.out(line);
     let report;
     try {
-        report = await fetchSandboxReport();
+        const connection = await connect(deps, "management", options.tenant);
+        report = (await managementClient(deps, connection).settings.sandbox.get());
     }
     catch (error) {
+        if (error instanceof CliError)
+            throw error;
         throw new CliError(error instanceof Error
             ? error.message
             : `Could not read Tenant sandbox status: ${String(error)}`, 1);
     }
     if (options.json) {
-        console.log(JSON.stringify({ platform: platformLine(), ...report }, null, 2));
+        log(JSON.stringify({ platform: platformLine(), ...report }, null, 2));
         return;
     }
     const rows = [["platform", platformLine()]];
@@ -42,14 +43,21 @@ export async function doctorSandbox(options) {
             ? "auto (npx nylorun start seeds the Tenant's sandbox.backend from .env NYLORUN_SANDBOX)"
             : report.preference,
     ]);
-    if (report.config)
+    rows.push([
+        "sessions",
+        "get a sandbox only on an Environment (createSession({ environment }) names one)",
+    ]);
+    const limits = report.config?.limits;
+    if (limits)
         rows.push([
-            "default",
-            report.config.default === "none"
-                ? "none: sessions get a sandbox only when opened with one (set a default with PUT /v1/tenant/sandbox)"
-                : report.config.default === "virtual"
-                    ? "virtual: sessions that name no sandbox get one"
-                    : "a Tenant sandbox: sessions that name no sandbox get it",
+            "limits",
+            [
+                limits.idle ? `idle ${limits.idle}` : undefined,
+                limits.environments === undefined ? undefined : `${limits.environments} environments`,
+                limits.network ? `${limits.network.length} allowed hosts` : undefined,
+            ]
+                .filter((item) => item !== undefined)
+                .join(", ") || "-",
         ]);
     rows.push([
         "selected",
@@ -59,7 +67,7 @@ export async function doctorSandbox(options) {
     ]);
     const width = Math.max(...rows.map(([key]) => key.length)) + 2;
     for (const [key, value] of rows)
-        console.log(`  ${key.padEnd(width)}${value}`);
+        log(`  ${key.padEnd(width)}${value}`);
     if (report.backend === "virtual")
-        console.log("\n  The virtual shell emulates bash in the Runtime process; it is not a VM boundary.");
+        log("\n  The virtual shell emulates bash in the Runtime process; it is not a VM boundary.");
 }

package/dist/client/environment-manifests.d.ts

@@ -0,0 +1,10 @@
+import { type EnvironmentManifestInput } from "@nylorun/agents";
+import type { StackDeps } from "../stack/commands.js";
+export declare const manifestsUsage = "  manifests list [--json]             each environment manifest's latest version\n  manifests get <name> [--version <n>]\n                                      a manifest's latest version (or version n), as JSON\n  manifests versions <name>           its versions, with the Environments made from each\n  manifests save <manifest.json>... [--if-match <n>] [--dry-run]\n                                      save each manifest's next version (a files entry with\n                                      \"from\": a folder beside the file, uploaded by hash);\n                                      --dry-run prints the plan and saves nothing\n  manifests rm <name>                 delete every version (refused while an Environment\n                                      was made from one)";
+/** The manifest in `path`, its `from` folders hashed: the body to save and the bytes to upload. */
+export declare function manifestFrom(path: string): Promise<{
+    manifest: EnvironmentManifestInput;
+    bytes: Record<string, Uint8Array>;
+}>;
+/** `nylorun environments manifests <command> ...` */
+export declare function manifestsCommand(deps: StackDeps, args: readonly string[], usage: string): Promise<number>;

package/dist/client/environment-manifests.js

@@ -0,0 +1,173 @@
+/**
+ * `nylorun environments manifests`: the Tenant's environment manifests (protocol 14, D63), named
+ * and versioned definitions of a kind of Environment, saved like agents. `save` reads each JSON
+ * file (its `$schema` is dropped), turns a `files` entry with `from` (a folder, relative to the
+ * file) into files by content hash and uploads those the Runtime lacks, then saves the next
+ * version under `If-Match` when `--if-match` is given. `--dry-run` prints the plan and exits 1
+ * when the Runtime would refuse the save.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { environmentFiles } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { integerFlag, parseFlags, positional, printJson, printTable, readJson, runtimeCall, runtimeClient, usageError, } from "./runtime.js";
+export const manifestsUsage = `  manifests list [--json]             each environment manifest's latest version
+  manifests get <name> [--version <n>]
+                                      a manifest's latest version (or version n), as JSON
+  manifests versions <name>           its versions, with the Environments made from each
+  manifests save <manifest.json>... [--if-match <n>] [--dry-run]
+                                      save each manifest's next version (a files entry with
+                                      "from": a folder beside the file, uploaded by hash);
+                                      --dry-run prints the plan and saves nothing
+  manifests rm <name>                 delete every version (refused while an Environment
+                                      was made from one)`;
+/** Each file under `dir`, by its path relative to it (`/`-separated). */
+async function folderOf(dir) {
+    const found = {};
+    const visit = async (at) => {
+        for (const entry of await readdir(at, { withFileTypes: true })) {
+            const path = join(at, entry.name);
+            if (entry.isDirectory())
+                await visit(path);
+            else if (entry.isFile())
+                found[relative(dir, path).split(sep).join("/")] = new Uint8Array(await readFile(path));
+        }
+    };
+    try {
+        await visit(dir);
+    }
+    catch (error) {
+        throw new CliError(`Cannot read ${dir}: ${error.message}`, 1);
+    }
+    if (Object.keys(found).length === 0)
+        throw new CliError(`${dir} holds no files.`, 1);
+    return found;
+}
+/** The manifest in `path`, its `from` folders hashed: the body to save and the bytes to upload. */
+export async function manifestFrom(path) {
+    const raw = await readJson(path, "The manifest");
+    if (typeof raw.name !== "string" || raw.name === "")
+        throw usageError(`${path}: the manifest has no name.`);
+    const bytes = {};
+    const files = Array.isArray(raw.files) ? raw.files : undefined;
+    const entries = [];
+    for (const entry of files ?? []) {
+        if (typeof entry?.from !== "string") {
+            entries.push(entry);
+            continue;
+        }
+        const { from, ...rest } = entry;
+        if (typeof rest.path !== "string")
+            throw usageError(`${path}: a files entry with from needs a path.`);
+        const folder = await environmentFiles(rest.path, await folderOf(resolve(dirname(path), from)));
+        Object.assign(bytes, folder.bytes);
+        entries.push({ ...rest, files: folder.entry.files });
+    }
+    const { $schema: _schema, ...manifest } = raw;
+    return {
+        manifest: (files === undefined ? manifest : { ...manifest, files: entries }),
+        bytes,
+    };
+}
+async function save(deps, args) {
+    const usage = "nylorun environments manifests save <manifest.json>... [--if-match <n>] [--dry-run]";
+    const flags = parseFlags(args, { booleans: ["--dry-run"], values: ["--if-match"] }, usage);
+    if (flags.rest.length === 0)
+        throw usageError(`Usage: ${usage}`);
+    const ifMatch = integerFlag(flags, "--if-match");
+    if (ifMatch !== undefined && flags.rest.length > 1)
+        throw usageError("--if-match takes one manifest.");
+    const { client, connection } = await runtimeClient(deps, flags);
+    let blocked = false;
+    for (const path of flags.rest) {
+        const { manifest, bytes } = await manifestFrom(path);
+        const options = { files: bytes, ...(ifMatch === undefined ? {} : { ifMatch }) };
+        if (flags.booleans.has("--dry-run")) {
+            const plan = await runtimeCall(() => client.environments.manifests.plan(manifest, options));
+            printJson(deps, plan);
+            if (plan.errors.length > 0)
+                blocked = true;
+            continue;
+        }
+        const saved = await runtimeCall(() => client.environments.manifests.save(manifest, options));
+        deps.err(saved.unchanged
+            ? `Environment manifest ${saved.manifest.name} is unchanged at version ${saved.manifest.version} on ${connection.label}.`
+            : `Saved environment manifest ${saved.manifest.name} version ${saved.manifest.version} on ${connection.label}.`);
+        for (const warning of saved.warnings)
+            deps.err(`  warning: ${warning.message}`);
+        printJson(deps, saved);
+    }
+    return blocked ? 1 : 0;
+}
+async function list(deps, args) {
+    const usage = "nylorun environments manifests list [--json]";
+    const flags = parseFlags(args, { booleans: ["--json"] }, usage);
+    positional(flags, 0, usage);
+    const { client, connection } = await runtimeClient(deps, flags);
+    const manifests = await runtimeCall(() => client.environments.manifests.list());
+    if (flags.booleans.has("--json")) {
+        printJson(deps, manifests);
+        return 0;
+    }
+    if (manifests.length === 0)
+        deps.out(`No environment manifests on ${connection.label}.`);
+    else
+        printTable(deps, [
+            ["NAME", "VERSION", "KIND", "ENVIRONMENTS", "SAVED BY"],
+            ...manifests.map((manifest) => [
+                manifest.name,
+                String(manifest.version),
+                manifest.manifest.kind ?? "virtual",
+                String(manifest.environments),
+                manifest.savedBy.actor,
+            ]),
+        ]);
+    return 0;
+}
+async function get(deps, args) {
+    const usage = "nylorun environments manifests get <name> [--version <n>]";
+    const flags = parseFlags(args, { values: ["--version"] }, usage);
+    const [name] = positional(flags, 1, usage);
+    const version = integerFlag(flags, "--version");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.environments.manifests.get(name, version === undefined ? {} : { version })));
+    return 0;
+}
+async function versions(deps, args) {
+    const usage = "nylorun environments manifests versions <name>";
+    const flags = parseFlags(args, {}, usage);
+    const [name] = positional(flags, 1, usage);
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.environments.manifests.versions(name)));
+    return 0;
+}
+async function remove(deps, args) {
+    const usage = "nylorun environments manifests rm <name>";
+    const flags = parseFlags(args, {}, usage);
+    const [name] = positional(flags, 1, usage);
+    const { client, connection } = await runtimeClient(deps, flags);
+    const deleted = await runtimeCall(() => client.environments.manifests.delete(name));
+    if (!deleted.deleted) {
+        deps.err(`No environment manifest ${name} on ${connection.label}.`);
+        return 1;
+    }
+    deps.out(`Deleted environment manifest ${name}: every version.`);
+    return 0;
+}
+const COMMANDS = {
+    list,
+    ls: list,
+    get,
+    versions,
+    save,
+    rm: remove,
+    delete: remove,
+};
+/** `nylorun environments manifests <command> ...` */
+export async function manifestsCommand(deps, args, usage) {
+    const [sub, ...rest] = args;
+    const command = sub !== undefined && Object.hasOwn(COMMANDS, sub) ? COMMANDS[sub] : undefined;
+    if (!command)
+        throw usageError(`Usage: nylorun environments manifests <list|get|versions|save|rm> …\n\n${usage}`);
+    return command(deps, rest);
+}

package/dist/client/environments.d.ts

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

package/dist/client/environments.js

@@ -0,0 +1,295 @@
+import { manifestsCommand, manifestsUsage } from "./environment-manifests.js";
+import { readSecret } from "./io.js";
+import { integerFlag, labelsOf, parseFlags, positional, printCursor, printJson, printTable, readJson, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError, } from "./runtime.js";
+export const environmentsUsage = `nylorun environments <command>
+
+The Tenant's Environments (one sandbox and one vault each), through the Runtime API with an
+application key (or NYLORUN_TOKEN).
+
+  list [--label <key=value>]... [--behind] [--limit <n>] [--cursor <c>] [--json]
+                                      id, kind, manifest, state, sessions and labels;
+                                      --behind: those made from an older manifest version
+  get <id>                            the Environment, as JSON
+  put <id> --manifest <name[@n]> [--label <key=value>]...
+  put <id> [<inline.json|->] [--kind <virtual|pod|none>] [--label <key=value>]...
+                                      create it from a manifest (its latest version, or n)
+                                      or inline fields, or find it and change its labels
+                                      (what it runs never changes: fork it for that)
+  fork <id> <new-id> [--manifest <name[@n]>] [--disk <latest|n|empty>]
+       [--secrets <copy|none>] [--label <key=value>]... [--dry-run]
+                                      a new Environment from a manifest version (default
+                                      its manifest's latest), with this one's disk and the
+                                      secrets it declares; --dry-run prints the plan
+  stop <id> | reset <id>              stop its sandbox; reset its disk
+  delete <id>                         delete it: its sandbox, files and vault (refused while a
+                                      turn runs in it)
+  snapshot <id>                       keep a version of its disk
+  versions <id>                       its disk versions
+  restore <id> <version|latest>       put a version of its disk back
+  delete-version <id> <version>
+  events <id> [--from <n>] [--types <type,…>] [--since <time>] [--until <time>]
+                                      its events (lifecycle, and environment.egress for every
+                                      connection, naming the turns running), as JSON
+  secrets list <id>                   its secrets' names, types and bindings (never a value)
+  secrets get <id> <name>
+  secrets put <id> <name>             the value of a slot its manifest declares, piped in
+                                      on standard input
+  secrets put <id> <name> <secret.json|->
+                                      create or replace a secret: {"type": "bearer", ...}, read
+                                      from a file or standard input
+  secrets rm <id> <name>
+${manifestsUsage}
+
+${runtimeFlagsUsage}`;
+async function list(deps, args) {
+    const usage = "nylorun environments list [--label <key=value>]... [--behind] [--limit <n>] [--cursor <c>] [--json]";
+    const flags = parseFlags(args, { booleans: ["--json", "--behind"], values: ["--limit", "--cursor"], lists: ["--label"] }, usage);
+    positional(flags, 0, usage);
+    const labels = labelsOf(flags);
+    const limit = integerFlag(flags, "--limit");
+    const cursor = flags.values.get("--cursor");
+    const { client, connection } = await runtimeClient(deps, flags);
+    const paged = limit !== undefined || cursor !== undefined;
+    const page = paged
+        ? await runtimeCall(() => client.environments.page({
+            ...(labels ? { labels } : {}),
+            ...(limit === undefined ? {} : { limit }),
+            ...(cursor ? { cursor } : {}),
+        }))
+        : {
+            environments: await runtimeCall(() => client.environments.list(labels ? { labels } : {})),
+            nextCursor: null,
+        };
+    let environments = page.environments;
+    if (flags.booleans.has("--behind")) {
+        // Made from a manifest version older than its latest: fork them to move on (D63).
+        const latest = new Map((await runtimeCall(() => client.environments.manifests.list())).map((manifest) => [manifest.name, manifest.version]));
+        environments = environments.filter((environment) => environment.manifestName !== undefined &&
+            (environment.manifestVersion ?? 0) < (latest.get(environment.manifestName) ?? 0));
+    }
+    if (flags.booleans.has("--json")) {
+        printJson(deps, paged ? page : environments);
+        return 0;
+    }
+    if (environments.length === 0)
+        deps.out(`No Environments on ${connection.label}.`);
+    else
+        printTable(deps, [
+            ["ID", "KIND", "MANIFEST", "STATE", "SESSIONS", "LABELS"],
+            ...environments.map((environment) => [
+                environment.id,
+                environment.kind,
+                environment.manifestName === undefined ? "-" : `${environment.manifestName}@${environment.manifestVersion}`,
+                environment.state,
+                String(environment.sessions.length),
+                Object.entries(environment.labels)
+                    .map(([key, value]) => `${key}=${value}`)
+                    .join(",") || "-",
+            ]),
+        ]);
+    printCursor(deps, page.nextCursor);
+    return 0;
+}
+/** A command that takes one Environment id and prints the Runtime's answer. */
+function byId(name, call) {
+    return async (deps, args) => {
+        const usage = `nylorun environments ${name} <id>`;
+        const flags = parseFlags(args, {}, usage);
+        const [id] = positional(flags, 1, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => call(client, id)));
+        return 0;
+    };
+}
+async function put(deps, args) {
+    const usage = "nylorun environments put <id> [--manifest <name[@n]> | <inline.json|-> [--kind <virtual|pod|none>]] [--label <key=value>]...";
+    const flags = parseFlags(args, { values: ["--kind", "--manifest"], lists: ["--label"] }, usage);
+    if (flags.rest.length < 1 || flags.rest.length > 2)
+        throw usageError(`Usage: ${usage}`);
+    const [id, path] = flags.rest;
+    const manifest = flags.values.get("--manifest");
+    const kind = flags.values.get("--kind");
+    if (manifest !== undefined && (path !== undefined || kind !== undefined))
+        throw usageError("--manifest makes it from the manifest: give no inline fields or --kind with it.");
+    const recipe = path === undefined ? {} : await readJson(path, "The inline fields");
+    const labels = labelsOf(flags);
+    const body = {
+        ...recipe,
+        ...(manifest ? { manifest } : {}),
+        ...(kind ? { kind } : {}),
+        ...(labels ? { labels: { ...recipe.labels, ...labels } } : {}),
+    };
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.environments.put(id, body)));
+    return 0;
+}
+async function fork(deps, args) {
+    const usage = "nylorun environments fork <id> <new-id> [--manifest <name[@n]>] [--disk <latest|n|empty>] [--secrets <copy|none>] [--label <key=value>]... [--dry-run]";
+    const flags = parseFlags(args, { booleans: ["--dry-run"], values: ["--manifest", "--disk", "--secrets"], lists: ["--label"] }, usage);
+    const [id, next] = positional(flags, 2, usage);
+    const disk = flags.values.get("--disk");
+    if (disk !== undefined && disk !== "latest" && disk !== "empty" && !/^[1-9]\d*$/.test(disk))
+        throw usageError("--disk is latest, empty or a version number.");
+    const secrets = flags.values.get("--secrets");
+    if (secrets !== undefined && secrets !== "copy" && secrets !== "none")
+        throw usageError("--secrets is copy or none.");
+    const manifest = flags.values.get("--manifest");
+    const labels = labelsOf(flags);
+    const options = {
+        id: next,
+        ...(manifest ? { manifest } : {}),
+        ...(disk === undefined ? {} : { disk: disk === "latest" || disk === "empty" ? disk : Number(disk) }),
+        ...(secrets ? { secrets: secrets } : {}),
+        ...(labels ? { labels } : {}),
+    };
+    const { client, connection } = await runtimeClient(deps, flags);
+    if (flags.booleans.has("--dry-run")) {
+        printJson(deps, await runtimeCall(() => client.environments.planFork(id, options)));
+        return 0;
+    }
+    const forked = await runtimeCall(() => client.environments.fork(id, options));
+    const { plan } = forked;
+    deps.err(`Forked Environment ${id} into ${next} on ${connection.label}: ${plan.manifest ? `${plan.manifest.name}@${plan.manifest.version}` : "its fields"}, ${plan.disk === null ? "an empty disk" : `disk version ${plan.disk}`}, ${plan.secrets.copied.length} secrets copied${plan.setup ? "; its setup runs before the first turn" : ""}.`);
+    if (plan.secrets.missing.length > 0)
+        deps.err(`  set before use: ${plan.secrets.missing.join(", ")} (nylorun environments secrets put ${next} <name>)`);
+    printJson(deps, forked);
+    return 0;
+}
+async function deleteEnvironment(deps, args) {
+    const usage = "nylorun environments delete <id>";
+    const flags = parseFlags(args, {}, usage);
+    const [id] = positional(flags, 1, usage);
+    const { client, connection } = await runtimeClient(deps, flags);
+    const deleted = await runtimeCall(async () => {
+        try {
+            return await client.environments.delete(id);
+        }
+        catch (error) {
+            if (error.status === 404)
+                return undefined;
+            throw error;
+        }
+    });
+    if (!deleted || deleted.deleted === false) {
+        deps.err(`No Environment ${id} on ${connection.label}.`);
+        return 1;
+    }
+    deps.out(`Deleted Environment ${id}: its sandbox, files and vault.`);
+    return 0;
+}
+async function restore(deps, args) {
+    const usage = "nylorun environments restore <id> <version|latest>";
+    const flags = parseFlags(args, {}, usage);
+    const [id, version] = positional(flags, 2, usage);
+    if (version !== "latest" && !/^[1-9]\d*$/.test(version))
+        throw usageError("The version is a positive number or latest.");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.environments.restore(id, version === "latest" ? "latest" : Number(version))));
+    return 0;
+}
+async function deleteVersion(deps, args) {
+    const usage = "nylorun environments delete-version <id> <version>";
+    const flags = parseFlags(args, {}, usage);
+    const [id, version] = positional(flags, 2, usage);
+    if (!/^[1-9]\d*$/.test(version))
+        throw usageError("The version is a positive number.");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.environments.deleteVersion(id, Number(version))));
+    return 0;
+}
+async function events(deps, args) {
+    const usage = "nylorun environments events <id> [--from <n>] [--types <type,…>] [--since <time>] [--until <time>]";
+    const flags = parseFlags(args, { values: ["--from", "--types", "--since", "--until"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const from = integerFlag(flags, "--from");
+    const types = flags.values.get("--types")?.split(",").map((type) => type.trim()).filter(Boolean);
+    const since = flags.values.get("--since");
+    const until = flags.values.get("--until");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.environments.events(id, {
+        ...(from === undefined ? {} : { from }),
+        ...(types === undefined || types.length === 0 ? {} : { types }),
+        ...(since === undefined ? {} : { since }),
+        ...(until === undefined ? {} : { until }),
+    })));
+    return 0;
+}
+async function secrets(deps, args) {
+    const [verb, ...rest] = args;
+    if (verb === "list" || verb === "ls") {
+        const usage = "nylorun environments secrets list <id>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id] = positional(flags, 1, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.environments.secrets.list(id)));
+        return 0;
+    }
+    if (verb === "get") {
+        const usage = "nylorun environments secrets get <id> <name>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id, name] = positional(flags, 2, usage);
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.environments.secrets.get(id, name)));
+        return 0;
+    }
+    if (verb === "put") {
+        const usage = "nylorun environments secrets put <id> <name> [<secret.json|->]";
+        const flags = parseFlags(rest, {}, usage);
+        if (flags.rest.length < 2 || flags.rest.length > 3)
+            throw usageError(`Usage: ${usage}`);
+        const [id, name, path] = flags.rest;
+        if (path === undefined) {
+            // A slot its manifest declares (D64): the value only, piped in; the binding is the slot's.
+            const value = await readSecret(deps, `value of ${name}`, `printf %s "$TOKEN" | nylorun environments secrets put ${id} ${name}`);
+            const { client } = await runtimeClient(deps, flags);
+            printJson(deps, await runtimeCall(() => client.environments.secrets.put(id, name, { value })));
+            return 0;
+        }
+        const secret = await readJson(path, "The secret");
+        if (typeof secret.type !== "string")
+            throw usageError('The secret needs a "type".');
+        const { client } = await runtimeClient(deps, flags);
+        printJson(deps, await runtimeCall(() => client.environments.secrets.put(id, name, secret)));
+        return 0;
+    }
+    if (verb === "rm" || verb === "delete") {
+        const usage = "nylorun environments secrets rm <id> <name>";
+        const flags = parseFlags(rest, {}, usage);
+        const [id, name] = positional(flags, 2, usage);
+        const { client } = await runtimeClient(deps, flags);
+        await runtimeCall(() => client.environments.secrets.delete(id, name));
+        deps.out(`Deleted secret ${name} of Environment ${id}.`);
+        return 0;
+    }
+    throw usageError(`Usage: nylorun environments secrets <list|get|put|rm> …\n\n${environmentsUsage}`);
+}
+const COMMANDS = {
+    list,
+    ls: list,
+    get: byId("get", (client, id) => client.environments.get(id)),
+    put,
+    stop: byId("stop", (client, id) => client.environments.stop(id)),
+    reset: byId("reset", (client, id) => client.environments.reset(id)),
+    delete: deleteEnvironment,
+    rm: deleteEnvironment,
+    snapshot: byId("snapshot", (client, id) => client.environments.snapshot(id)),
+    versions: byId("versions", (client, id) => client.environments.versions(id)),
+    restore,
+    "delete-version": deleteVersion,
+    events,
+    secrets,
+    fork,
+    manifests: (deps, args) => manifestsCommand(deps, args, manifestsUsage),
+};
+/** `nylorun environments <command> ...` */
+export async function environmentsCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "--help" || sub === "-h") {
+        deps.out(environmentsUsage);
+        return 0;
+    }
+    const command = sub !== undefined && Object.hasOwn(COMMANDS, sub) ? COMMANDS[sub] : undefined;
+    if (!command)
+        throw usageError(sub ? `Unknown environments command ${sub}.\n${environmentsUsage}` : environmentsUsage);
+    return command(deps, rest);
+}

package/dist/client/io.d.ts

@@ -0,0 +1,31 @@
+import type { StackDeps } from "../stack/commands.js";
+/** A request schema (`@nylorun/core/contracts`), as far as reading a body needs it. */
+export interface BodySchema<T> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: readonly {
+                path: readonly PropertyKey[];
+                message: string;
+            }[];
+        };
+    };
+}
+/**
+ * The JSON body in file `source`, or on standard input for `-`, as `schema` parses it. Fields
+ * named in `readOnly` (a view's, so a `get` can be edited and put back) are dropped first. A
+ * body that does not parse is a usage error, before any request.
+ */
+export declare function readBody<T>(deps: StackDeps, source: string, schema: BodySchema<T>, readOnly?: readonly string[]): Promise<T>;
+/**
+ * A secret piped in on standard input (its trailing newline dropped), so it is never in the
+ * arguments, the shell's history or the process list. `what` names it in the refusals.
+ */
+export declare function readSecret(deps: StackDeps, what: string, example: string): Promise<string>;
+/** `rows` (the first is the header) as columns two spaces apart, with no trailing blanks. */
+export declare function printTable(deps: StackDeps, rows: readonly (readonly string[])[]): void;
+/** `value` as indented JSON on stdout. */
+export declare function printJson(deps: StackDeps, value: unknown): void;