withruntime 0.17.2 → 0.18.0

package/dist/apps-cli.d.ts

@@ -0,0 +1,12 @@
+import type { CliKit } from "./cli.js";
+import type { Runtime } from "./client.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+export declare const APP_HELP = "runtime apps <command>\n\n  An App serves your web server from an image or a build. Copies start when\n  requests come and stop when they end, between --min-copies and --max-copies.\n  In a private beta: outside it, each command says how to ask to join.\n\n  create [<name>] --vcpu <1-16> --memory <128-65536> --max-copies <1-1000>\n         [--min-copies 0] [--concurrency 100] [--spares 2] [--port 8080]\n         [--health-path /healthz] [--label key=value]...\n                                              Make an App, waiting for its first deploy; prints its id\n  ls [--all]                                  Your Apps: state, live version, copies; --all, deleted too\n  get <app>                                   One App, in full (an id or its name)\n  update <app> [--name <name>] [--vcpu n] [--memory n] [--min-copies n] [--max-copies n]\n         [--concurrency n] [--spares n] [--port n] [--health-path /path] [--label key=value]...\n                                              Change its settings\n  rm <app>                                    Delete it and stop its copies\n  deploy <app> (--image <image> | --build <buildId>) [--env KEY=VALUE]... [--keep-env]\n         [--port 8080] [--health-path /healthz] [--no-wait]\n                                              A new version. Waits until it is live, or says why it\n                                              failed; --no-wait prints the deploy's id at once.\n                                              --image: an image of yours (id, name, name:tag);\n                                              --build: a build that succeeded (runtime builds).\n                                              --env KEY alone sends KEY's value from your environment.\n                                              --keep-env keeps the last deploy's environment, sealed\n  deploys <app> [<deployId>] [--wait]         Each version's deploy: state and address; with an id,\n                                              that one (--wait: until it ends)\n  versions <app>                              Its versions; the live and previous ones keep saved copies\n  copies <app>                                Its copies now: version, region, state\n  rollback <app> [--no-wait]                  Put the previous version live again\n\nExamples\n  runtime apps create web --vcpu 1 --memory 512 --max-copies 3\n  runtime apps deploy web --image web:latest --env NODE_ENV=production\n  runtime apps rollback web\n";
+export declare const BUILD_HELP = "runtime builds <command>\n\n  A build turns a commit of a connected repository into a saved server an App\n  deploys. A push to the production branch builds and deploys by itself.\n  In a private beta: outside it, each command says how to ask to join.\n\n  repos connect <owner/name | https URL> --deploy <app name> [--branch main] [--no-previews]\n        [--root <folder>] [--install <command>] [--build <command>] [--start <command>]\n        [--port 8080] [--health-path /healthz] [--build-env KEY=VALUE]... [--name <name>]\n                                              Connect a repository; prints its id. --deploy takes an\n                                              App's name, or function:<name>. --start runs once the\n                                              build is done, with PORT set: the server the App deploys\n  repos ls                                    Connected repositories\n  repos change <repoId> [the options of connect but the repository]\n                                              Change its settings; its id and builds stay\n  repos disconnect <repoId>                   Stop building it; its builds stay\n  repos install                               A link to install Runtime's GitHub App, so a private\n                                              repository builds\n  create <repoId> [--ref main] [--branch <name>] [--name <name>]\n                                              Build a branch, tag or commit now; prints the build's id\n  run <repoId> [--ref main] [--branch <name>] [--name <name>] [--raw]\n                                              The same, then follows its log; exits 0 once it succeeds\n  ls [--repository <repoId>] [--commit <sha>] [--state <state>]...\n                                              Builds, oldest first; --commit: a full sha\n  get <buildId>                               One build: state, commit, step times, what it made\n  cancel <buildId>                            Stop a build that has not ended\n  logs <buildId> [--follow] [--raw]           Its last 200 lines, or every line as it comes until it\n                                              ends; on a terminal control characters show as \\uXXXX\n                                              unless --raw\n\nExamples\n  runtime builds repos connect acme/web --deploy web --start \"npm start\"\n  runtime builds run <repoId> --ref main\n  runtime builds ls --commit $(git rev-parse HEAD)\n";
+export declare function appsCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
+export declare function buildsCommand(argv: string[], out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
+export {};

package/dist/apps-cli.js

@@ -0,0 +1,564 @@
+import { me, named } from "./cli-name.js";
+import { RuntimeError } from "./errors.js";
+import { logStream } from "./terminal.js";
+import { apps, } from "./products/apps.js";
+import { builds, } from "./products/builds.js";
+export const APP_HELP = `runtime apps <command>
+
+  An App serves your web server from an image or a build. Copies start when
+  requests come and stop when they end, between --min-copies and --max-copies.
+  In a private beta: outside it, each command says how to ask to join.
+
+  create [<name>] --vcpu <1-16> --memory <128-65536> --max-copies <1-1000>
+         [--min-copies 0] [--concurrency 100] [--spares 2] [--port 8080]
+         [--health-path /healthz] [--label key=value]...
+                                              Make an App, waiting for its first deploy; prints its id
+  ls [--all]                                  Your Apps: state, live version, copies; --all, deleted too
+  get <app>                                   One App, in full (an id or its name)
+  update <app> [--name <name>] [--vcpu n] [--memory n] [--min-copies n] [--max-copies n]
+         [--concurrency n] [--spares n] [--port n] [--health-path /path] [--label key=value]...
+                                              Change its settings
+  rm <app>                                    Delete it and stop its copies
+  deploy <app> (--image <image> | --build <buildId>) [--env KEY=VALUE]... [--keep-env]
+         [--port 8080] [--health-path /healthz] [--no-wait]
+                                              A new version. Waits until it is live, or says why it
+                                              failed; --no-wait prints the deploy's id at once.
+                                              --image: an image of yours (id, name, name:tag);
+                                              --build: a build that succeeded (runtime builds).
+                                              --env KEY alone sends KEY's value from your environment.
+                                              --keep-env keeps the last deploy's environment, sealed
+  deploys <app> [<deployId>] [--wait]         Each version's deploy: state and address; with an id,
+                                              that one (--wait: until it ends)
+  versions <app>                              Its versions; the live and previous ones keep saved copies
+  copies <app>                                Its copies now: version, region, state
+  rollback <app> [--no-wait]                  Put the previous version live again
+
+Examples
+  runtime apps create web --vcpu 1 --memory 512 --max-copies 3
+  runtime apps deploy web --image web:latest --env NODE_ENV=production
+  runtime apps rollback web
+`;
+export const BUILD_HELP = `runtime builds <command>
+
+  A build turns a commit of a connected repository into a saved server an App
+  deploys. A push to the production branch builds and deploys by itself.
+  In a private beta: outside it, each command says how to ask to join.
+
+  repos connect <owner/name | https URL> --deploy <app name> [--branch main] [--no-previews]
+        [--root <folder>] [--install <command>] [--build <command>] [--start <command>]
+        [--port 8080] [--health-path /healthz] [--build-env KEY=VALUE]... [--name <name>]
+                                              Connect a repository; prints its id. --deploy takes an
+                                              App's name, or function:<name>. --start runs once the
+                                              build is done, with PORT set: the server the App deploys
+  repos ls                                    Connected repositories
+  repos change <repoId> [the options of connect but the repository]
+                                              Change its settings; its id and builds stay
+  repos disconnect <repoId>                   Stop building it; its builds stay
+  repos install                               A link to install Runtime's GitHub App, so a private
+                                              repository builds
+  create <repoId> [--ref main] [--branch <name>] [--name <name>]
+                                              Build a branch, tag or commit now; prints the build's id
+  run <repoId> [--ref main] [--branch <name>] [--name <name>] [--raw]
+                                              The same, then follows its log; exits 0 once it succeeds
+  ls [--repository <repoId>] [--commit <sha>] [--state <state>]...
+                                              Builds, oldest first; --commit: a full sha
+  get <buildId>                               One build: state, commit, step times, what it made
+  cancel <buildId>                            Stop a build that has not ended
+  logs <buildId> [--follow] [--raw]           Its last 200 lines, or every line as it comes until it
+                                              ends; on a terminal control characters show as \\uXXXX
+                                              unless --raw
+
+Examples
+  runtime builds repos connect acme/web --deploy web --start "npm start"
+  runtime builds run <repoId> --ref main
+  runtime builds ls --commit $(git rev-parse HEAD)
+`;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const when = (ms) => (ms == null ? "-" : new Date(ms).toISOString());
+const ENDED = ["succeeded", "failed", "cancelled", "superseded"];
+/** An App's id from its id or its name: a name is looked up among the Apps
+ * not deleted, and must be one App's alone. */
+async function appIdOf(api, target, kit) {
+    if (UUID.test(target))
+        return target;
+    const found = (await api.list({ name: target, state: ["waiting", "live", "failed"] })).data;
+    if (found.length === 1)
+        return found[0].id;
+    throw kit.usage(found.length
+        ? `${found.length} Apps are named ${target}; give one's id (${me} apps ls).`
+        : `No App is named ${target}. Your Apps: ${me} apps ls`);
+}
+/** The flags an App's settings are given with, as the API names them. */
+function settings(args, kit) {
+    const { integer, flag } = kit;
+    const number = (name, field) => integer(args, name) === undefined ? {} : { [field]: integer(args, name) };
+    return {
+        ...number("vcpu", "vcpu"),
+        ...number("memory", "memoryMiB"),
+        ...number("min-copies", "minCopies"),
+        ...number("max-copies", "maxCopies"),
+        ...number("concurrency", "concurrency"),
+        ...number("spares", "spares"),
+        ...number("port", "port"),
+        ...(flag(args, "health-path") === undefined ? {} : { healthPath: flag(args, "health-path") }),
+    };
+}
+const SETTINGS = [
+    "vcpu",
+    "memory",
+    "min-copies",
+    "max-copies",
+    "concurrency",
+    "spares",
+    "port",
+    "health-path",
+    "label",
+];
+/** A deploy that ended badly, said with its own words, hint and last output. */
+function deployFailure(deploy) {
+    if (!deploy.error)
+        return undefined;
+    const last = deploy.error.lastOutput?.trim();
+    return new RuntimeError({
+        code: deploy.error.code,
+        status: 0,
+        message: `Version ${deploy.version} did not go live: ${deploy.error.message}${last ? `\nIts last output:\n${last}` : ""}`,
+        hint: deploy.error.hint,
+        details: { deploy },
+    });
+}
+export async function appsCommand(argv, env, out, client, kit) {
+    const { parse, flag, has, need, pairs, envPairs, table, usage } = kit;
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(APP_HELP), { usage: named(APP_HELP) });
+        return 0;
+    }
+    const api = apps((await client()).transport);
+    const idOf = (target) => appIdOf(api, need(target, "an App's id or name"), kit);
+    switch (verb) {
+        case "create": {
+            const args = parse(rest, [], SETTINGS);
+            if (args.positional.length > 1)
+                throw usage(`Give one name: ${me} apps create web --vcpu 1 --memory 512 --max-copies 2`);
+            const given = settings(args, kit);
+            for (const [option, field] of [
+                ["vcpu", "vcpu"],
+                ["memory", "memoryMiB"],
+                ["max-copies", "maxCopies"],
+            ])
+                if (given[field] === undefined)
+                    throw usage(`Give --${option}: ${me} apps create ${args.positional[0] ?? "web"} --vcpu 1 --memory 512 --max-copies 2`);
+            const input = {
+                ...given,
+                ...(args.positional[0] ? { name: args.positional[0] } : {}),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+            };
+            const app = await api.create(input);
+            if (!out.json)
+                out.error(`Created ${app.name ?? app.id}, waiting for its first version. Deploy one: ${me} apps deploy ${app.name ?? app.id} --image <image>`);
+            print(app.id, app);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            const args = parse(rest, ["all"], []);
+            const all = await (await api.list({
+                limit: 100,
+                ...(has(args, "all")
+                    ? { state: ["waiting", "live", "failed", "deleting", "deleted"] }
+                    : {}),
+            })).toArray(Infinity);
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "STATE", "LIVE", "COPIES", "SIZE", "CREATED"],
+                    ...all.map((a) => [
+                        a.id,
+                        a.name ?? "-",
+                        a.state,
+                        a.liveVersion === null ? "-" : `v${a.liveVersion}`,
+                        `${a.minCopies}-${a.maxCopies}`,
+                        `${a.vcpu} vCPU, ${a.memoryMiB} MiB`,
+                        when(a.createdAt),
+                    ]),
+                ])
+                : `No Apps. Make one: ${me} apps create web --vcpu 1 --memory 512 --max-copies 2`, all);
+            return 0;
+        }
+        case "get": {
+            const app = await api.get(await idOf(rest[0]));
+            print(JSON.stringify(app, null, 2), app);
+            return 0;
+        }
+        case "update": {
+            const args = parse(rest, [], [...SETTINGS, "name"]);
+            const id = await idOf(args.positional[0]);
+            const change = {
+                ...settings(args, kit),
+                ...(flag(args, "name") === undefined ? {} : { name: flag(args, "name") }),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+            };
+            if (!Object.keys(change).length)
+                throw usage(`Give a setting to change, such as ${me} apps update ${args.positional[0]} --max-copies 4`);
+            const app = await api.update(id, change);
+            print(`${app.name ?? app.id} updated.`, app);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            const app = await api.delete(await idOf(rest[0]));
+            print(`${app.name ?? app.id} ${app.state}.`, app);
+            return 0;
+        }
+        case "deploy": {
+            const args = parse(rest, ["keep-env", "no-wait"], ["image", "build", "env", "port", "health-path"]);
+            const id = await idOf(args.positional[0]);
+            const image = flag(args, "image");
+            const build = flag(args, "build");
+            if ((image === undefined) === (build === undefined))
+                throw usage(`Give --image <image> to deploy an image of yours, or --build <buildId> for a build that succeeded.`);
+            const port = kit.integer(args, "port");
+            const healthPath = flag(args, "health-path");
+            const wait = !has(args, "no-wait");
+            const input = {
+                ...(image !== undefined ? { image } : { build: build }),
+                ...(args.flags.has("env") ? { env: envPairs(args, env) } : {}),
+                ...(has(args, "keep-env") ? { keepEnv: true } : {}),
+                ...(port === undefined ? {} : { port }),
+                ...(healthPath === undefined ? {} : { healthPath }),
+                wait,
+            };
+            if (wait && !out.json)
+                out.error(`Deploying ${args.positional[0]}...`);
+            const deploy = await api.deploy(id, input, { timeoutMs: 15 * 60_000 });
+            const failed = deployFailure(deploy);
+            if (failed && !out.json)
+                throw failed;
+            print(deploy.state === "live"
+                ? `Version ${deploy.version} is live at ${deploy.url}`
+                : `Version ${deploy.version}: ${deploy.state}. Follow it: ${me} apps deploys ${args.positional[0]} ${deploy.id} --wait`, deploy);
+            return failed ? 1 : 0;
+        }
+        case "deploys": {
+            const args = parse(rest, ["wait"], []);
+            const id = await idOf(args.positional[0]);
+            const deployId = args.positional[1];
+            if (deployId) {
+                const deploy = has(args, "wait")
+                    ? await api.waitDeploy(id, deployId, { timeoutMs: 15 * 60_000 })
+                    : await api.getDeploy(id, deployId);
+                const failed = deployFailure(deploy);
+                if (failed && !out.json)
+                    throw failed;
+                print(JSON.stringify(deploy, null, 2), deploy);
+                return failed ? 1 : 0;
+            }
+            // Newest first; a version's deploy is read once per line, so the list
+            // stops at the last 20.
+            const versions = (await api.versions(id)).sort((a, b) => b.version - a.version).slice(0, 20);
+            const deploys = await Promise.all(versions.map((v) => api.getDeploy(id, v.deploy)));
+            print(deploys.length
+                ? table([
+                    ["VERSION", "DEPLOY", "STATE", "FROM", "ADDRESS"],
+                    ...deploys.map((d, i) => [
+                        `v${d.version}${versions[i].live ? " (live)" : versions[i].previous ? " (previous)" : ""}`,
+                        d.id,
+                        d.state,
+                        versions[i].build ? `build ${versions[i].build}` : "image",
+                        d.url,
+                    ]),
+                ])
+                : `No deploys yet. Deploy one: ${me} apps deploy ${args.positional[0]} --image <image>`, deploys);
+            return 0;
+        }
+        case "versions": {
+            const id = await idOf(rest[0]);
+            const versions = (await api.versions(id)).sort((a, b) => b.version - a.version);
+            print(versions.length
+                ? table([
+                    ["VERSION", "LIVE", "PREVIOUS", "SAVED", "DEPLOY", "BUILD"],
+                    ...versions.map((v) => [
+                        `v${v.version}`,
+                        v.live ? "yes" : "-",
+                        v.previous ? "yes" : "-",
+                        v.saved ? "yes" : "-",
+                        v.deploy,
+                        v.build ?? "-",
+                    ]),
+                ])
+                : "No versions yet.", versions);
+            return 0;
+        }
+        case "copies": {
+            const id = await idOf(rest[0]);
+            const copies = await api.copies(id);
+            print(copies.length
+                ? table([
+                    ["COPY", "VERSION", "REGION", "STATE", "SINCE"],
+                    ...copies.map((c) => [c.id, `v${c.version}`, c.region, c.state, when(c.since)]),
+                ])
+                : "No copies awake. A request starts one.", copies);
+            return 0;
+        }
+        case "rollback": {
+            const args = parse(rest, ["no-wait"], []);
+            const id = await idOf(args.positional[0]);
+            const deploy = await api.rollback(id, {
+                wait: !has(args, "no-wait"),
+                timeoutMs: 15 * 60_000,
+            });
+            const failed = deployFailure(deploy);
+            if (failed && !out.json)
+                throw failed;
+            print(deploy.state === "live"
+                ? `Version ${deploy.version} is live again at ${deploy.url}`
+                : `Rolling back to version ${deploy.version}: ${deploy.state}.`, deploy);
+            return failed ? 1 : 0;
+        }
+    }
+    throw kit.unknown("apps command", verb, [
+        "create",
+        "ls",
+        "get",
+        "update",
+        "rm",
+        "deploy",
+        "deploys",
+        "versions",
+        "copies",
+        "rollback",
+    ]);
+}
+/** A repository as connect takes it: GitHub's owner/name, a github.com
+ * address read as that, or any other https address as plain git. */
+function source(repository) {
+    const github = /^(?:https:\/\/github\.com\/)?([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(repository);
+    return github ? { provider: "github", repository: github[1] } : { provider: "git", repository };
+}
+/** connect's and change's settings. */
+function repositorySettings(args, kit) {
+    const { flag, has, integer, pairs } = kit;
+    const text = (name, field) => flag(args, name) === undefined ? {} : { [field]: flag(args, name) };
+    const deploy = flag(args, "deploy");
+    return {
+        ...(deploy === undefined
+            ? {}
+            : {
+                deploy: (/^(app|function|container):/.test(deploy)
+                    ? deploy
+                    : `app:${deploy}`),
+            }),
+        ...text("branch", "productionBranch"),
+        ...(has(args, "no-previews") ? { previews: false } : {}),
+        ...text("root", "rootDirectory"),
+        ...text("install", "installCommand"),
+        ...text("build", "buildCommand"),
+        ...text("start", "startCommand"),
+        ...(integer(args, "port") === undefined ? {} : { port: integer(args, "port") }),
+        ...text("health-path", "healthPath"),
+        ...(args.flags.has("build-env") ? { buildEnv: pairs(args, "build-env") } : {}),
+        ...text("name", "name"),
+    };
+}
+const REPOSITORY_VALUES = [
+    "deploy",
+    "branch",
+    "root",
+    "install",
+    "build",
+    "start",
+    "port",
+    "health-path",
+    "build-env",
+    "name",
+];
+export async function buildsCommand(argv, out, client, kit) {
+    const { parse, flag, has, need, table, usage } = kit;
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(BUILD_HELP), { usage: named(BUILD_HELP) });
+        return 0;
+    }
+    const api = builds((await client()).transport);
+    const buildRow = (b) => [
+        b.id,
+        b.state,
+        b.ref,
+        b.commit ? b.commit.slice(0, 12) : "-",
+        when(b.createdAt),
+        b.reason ?? "-",
+    ];
+    /** A build's log, its last lines or followed to its end. */
+    const logs = async (id, follow, raw) => {
+        const [stdout, stderr] = [logStream(process.stdout, raw), logStream(process.stderr, raw)];
+        const write = (line) => (line.stream === "stderr" ? stderr : stdout)(line.text.endsWith("\n") ? line.text : `${line.text}\n`);
+        if (!follow) {
+            const log = await api.logs(id);
+            if (out.json) {
+                out.write(JSON.stringify(log));
+                return 0;
+            }
+            log.lines.forEach(write);
+            if (log.failingStep)
+                out.error(`[${log.state} at ${log.failingStep.name}${log.failingStep.exitCode === null ? "" : `, exit code ${log.failingStep.exitCode}`}]`);
+            else
+                out.error(ENDED.includes(log.state)
+                    ? `[${log.state}${log.reason ? `, ${log.reason}` : ""}]`
+                    : `[${log.state}; follow it: ${me} builds logs ${id} --follow]`);
+            return 0;
+        }
+        // A follow lasts until the build ends: no deadline of the SDK's own.
+        for await (const event of api.logs(id, { follow: true }, { timeoutMs: 0 })) {
+            if (out.json)
+                out.write(JSON.stringify(event));
+            else if (event.type === "line")
+                write(event);
+            else if (event.type === "gap")
+                out.error("[older lines were dropped before they were read; going on from the oldest kept]");
+            if (event.type === "terminal") {
+                if (!out.json) {
+                    out.error(`[${event.state}, ${event.reason}]`);
+                    if (event.failingStep)
+                        out.error(`${event.failingStep.name} failed${event.failingStep.exitCode === null ? "" : ` with exit code ${event.failingStep.exitCode}`}. Its last lines:\n${event.failingStep.lastLines.join("\n")}`);
+                }
+                return event.state === "succeeded" ? 0 : 1;
+            }
+        }
+        return 1;
+    };
+    switch (verb) {
+        case "repos":
+        case "repositories": {
+            const [action, ...more] = rest;
+            switch (action) {
+                case "connect": {
+                    const args = parse(more, ["no-previews"], REPOSITORY_VALUES);
+                    const repository = need(args.positional[0], "the repository, such as acme/web");
+                    const given = repositorySettings(args, kit);
+                    if (!given.deploy)
+                        throw usage(`Give --deploy with the App it deploys: ${me} builds repos connect ${repository} --deploy web`);
+                    const repo = await api.repositories.connect({
+                        ...source(repository),
+                        ...given,
+                    });
+                    if (!out.json)
+                        out.error(`Connected ${repo.repository}: a push to ${repo.productionBranch} builds and deploys ${repo.deploy}. Build now: ${me} builds run ${repo.id}`);
+                    print(repo.id, repo);
+                    return 0;
+                }
+                case "ls":
+                case "list": {
+                    const all = await (await api.repositories.list({ limit: 100 })).toArray(Infinity);
+                    print(all.length
+                        ? table([
+                            ["ID", "REPOSITORY", "BRANCH", "DEPLOYS", "STATE"],
+                            ...all.map((r) => [
+                                r.id,
+                                r.repository,
+                                r.productionBranch,
+                                r.deploy,
+                                r.state,
+                            ]),
+                        ])
+                        : `No repositories. Connect one: ${me} builds repos connect acme/web --deploy web`, all);
+                    return 0;
+                }
+                case "change":
+                case "update": {
+                    const args = parse(more, ["no-previews"], REPOSITORY_VALUES);
+                    const id = need(args.positional[0], "a repository's id");
+                    const change = repositorySettings(args, kit);
+                    if (!Object.keys(change).length)
+                        throw usage(`Give a setting to change, such as --branch main or --start "npm start".`);
+                    const repo = await api.repositories.update(id, change);
+                    print(`${repo.repository} changed.`, repo);
+                    return 0;
+                }
+                case "disconnect":
+                case "rm": {
+                    const repo = await api.repositories.disconnect(need(more[0], "a repository's id"));
+                    print(`${repo.repository} disconnected; its builds stay.`, repo);
+                    return 0;
+                }
+                case "install": {
+                    const link = await api.repositories.installGithub();
+                    print(`Open this within 15 minutes, install the App on the repositories Runtime may read, and confirm the organization:\n${link.url}`, link);
+                    return 0;
+                }
+            }
+            throw kit.unknown("repos command", action ?? "", [
+                "connect",
+                "ls",
+                "change",
+                "disconnect",
+                "install",
+            ]);
+        }
+        case "create":
+        case "run": {
+            const args = parse(rest, verb === "run" ? ["raw"] : [], ["ref", "branch", "name"]);
+            const repositoryId = need(args.positional[0], "a repository's id (runtime builds repos ls)");
+            const build = await api.create({
+                repositoryId,
+                ref: flag(args, "ref") ?? flag(args, "branch") ?? "main",
+                ...(flag(args, "branch") ? { branch: flag(args, "branch") } : {}),
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+            });
+            if (verb === "create") {
+                if (!out.json)
+                    out.error(`Building ${build.ref}${build.commit ? ` at ${build.commit.slice(0, 12)}` : ""}. Follow it: ${me} builds logs ${build.id} --follow`);
+                print(build.id, build);
+                return 0;
+            }
+            if (!out.json)
+                out.error(`Build ${build.id}, ${build.ref}${build.commit ? ` at ${build.commit.slice(0, 12)}` : ""}:`);
+            else
+                out.write(JSON.stringify(build));
+            return logs(build.id, true, has(args, "raw"));
+        }
+        case "ls":
+        case "list": {
+            const args = parse(rest, [], ["repository", "commit", "state"]);
+            const commit = flag(args, "commit");
+            if (commit !== undefined && !/^([0-9a-f]{40}|[0-9a-f]{64})$/.test(commit))
+                throw usage(`--commit takes a full sha in lower case: ${me} builds ls --commit $(git rev-parse HEAD)`);
+            const states = args.flags.get("state");
+            const all = await (await api.list({
+                limit: 100,
+                ...(flag(args, "repository") ? { repositoryId: flag(args, "repository") } : {}),
+                ...(commit ? { commit } : {}),
+                ...(states ? { state: states } : {}),
+            })).toArray(Infinity);
+            print(all.length
+                ? table([["ID", "STATE", "REF", "COMMIT", "CREATED", "REASON"], ...all.map(buildRow)])
+                : "No builds.", all);
+            return 0;
+        }
+        case "get": {
+            const build = await api.get(need(rest[0], "a build's id"));
+            print(JSON.stringify(build, null, 2), build);
+            return 0;
+        }
+        case "cancel": {
+            const build = await api.cancel(need(rest[0], "a build's id"));
+            print(`${build.id} ${build.state}.`, build);
+            return 0;
+        }
+        case "logs": {
+            const args = parse(rest, ["f", "follow", "raw"], []);
+            const id = need(args.positional[0], "a build's id");
+            return logs(id, has(args, "f") || has(args, "follow"), has(args, "raw"));
+        }
+    }
+    throw kit.unknown("builds command", verb, [
+        "repos",
+        "create",
+        "run",
+        "ls",
+        "get",
+        "cancel",
+        "logs",
+    ]);
+}

package/dist/cli-words.js

@@ -1,3 +1,4 @@
+import { me } from "./cli-name.js";
 import { RuntimeError } from "./errors.js";
 import { cliWords } from "./product-renames.js";
 /* What the CLI says in its own words where the API's would mislead: the
@@ -48,6 +49,15 @@ function issueWords(path, message) {
  * a hint that names the options rather than the request's fields. Anything
  * else is left as the API said it. */
 export function cliRefusal(error) {
+    // A beta's refusal names the support tool an agent calls; here, the command.
+    if (error.code === "product_in_beta") {
+        const product = typeof error.details?.product === "string" ? error.details.product : "";
+        const open = (error.hint ?? "").replace(/;?\s*ask Runtime support \(runtime_support\) to join it\.?$/, ".");
+        return {
+            message: error.message,
+            hint: `${open ? `${open} ` : ""}Ask to join: ${me} support "Please add us to the ${product || "product"} beta"`,
+        };
+    }
     const issues = error.details?.issues;
     if (error.code === "invalid_request" && Array.isArray(issues) && issues.length) {
         const lines = issues

package/dist/cli.d.ts

@@ -24,9 +24,13 @@ declare const kit: {
     pairs: (args: Args, name: string) => {
         [k: string]: string;
     };
+    envPairs: (args: Args, from: NodeJS.ProcessEnv) => {
+        [k: string]: string;
+    };
     need: (value: string | undefined, what: string) => string;
     table: (rows: string[][]) => string;
     usage: (message: string) => RuntimeError;
+    unknown: (what: string, word: string, choices: readonly string[]) => RuntimeError;
 };
 export type CliKit = typeof kit;
 export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out): Promise<number>;

package/dist/cli.js

@@ -109,6 +109,8 @@ Products
   images     Custom images from a Dockerfile, any public or private image, or a package list
   volumes    Persistent disks to attach to sandboxes
   jobs       A command in a fresh sandbox, once or on a cron schedule, with its logs
+  apps       Your web server from an image or a build, copies started by requests (beta)
+  builds     A connected repository's commits built into what an App deploys (beta)
   domains    Your own hostname for a sandbox's port, with HTTPS
   ports      A public TCP port to a sandbox: databases, game servers
   ips        A dedicated outbound address, for allow-lists
@@ -357,9 +359,11 @@ const kit = {
     has,
     integer,
     pairs,
+    envPairs,
     need: (value, what) => need(value, what),
     table: (rows) => table(rows),
     usage: (message) => usage(message),
+    unknown: (what, word, choices) => unknown(what, word, choices),
 };
 /** The product being run, so a mistake points at its own help. */
 let product = "";
@@ -421,6 +425,8 @@ const COMMANDS = [
     "images",
     "volumes",
     "jobs",
+    "apps",
+    "builds",
     "domains",
     "ports",
     "ips",
@@ -439,6 +445,8 @@ const OWN_HELP = [
     "images",
     "volumes",
     "jobs",
+    "apps",
+    "builds",
     "keys",
     "webhooks",
     "webhook",
@@ -1095,6 +1103,14 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "job";
         return jobCommand(rest, env, out);
     }
+    if (command === "app" || command === "apps") {
+        product = "apps";
+        return (await import("./apps-cli.js")).appsCommand(rest, env, out, () => client(env), kit);
+    }
+    if (command === "build" || command === "builds") {
+        product = "builds";
+        return (await import("./apps-cli.js")).buildsCommand(rest, out, () => client(env), kit);
+    }
     // WireGuard is inside networks: `runtime networks wireguard peer add`.
     const wireguard = command === "networks" && rest[0] === "wireguard";
     const networkProduct = wireguard ? "wireguard" : command;

package/dist/daytona/sandbox.d.ts

@@ -126,7 +126,8 @@ export declare class Sandbox {
     /** Pauses the sandbox with its memory. */
     pause(_timeout?: number): Promise<void>;
     /** Runtime has no archive tier: a stopped sandbox stays paused, kept for
-     * its retention (30 days paid, 7 without credit, or autoDeleteInterval). */
+     * its retention (while the account has credit, 7 days without, or
+     * autoDeleteInterval rounded up to whole days). */
     archive(): Promise<void>;
     /** Ends the sandbox for good. */
     delete(_timeout?: number): Promise<void>;

package/dist/daytona/sandbox.js

@@ -270,7 +270,8 @@ export class Sandbox {
         this.#pausedByPause = true;
     }
     /** Runtime has no archive tier: a stopped sandbox stays paused, kept for
-     * its retention (30 days paid, 7 without credit, or autoDeleteInterval). */
+     * its retention (while the account has credit, 7 days without, or
+     * autoDeleteInterval rounded up to whole days). */
     async archive() {
         await this.stop();
     }

package/dist/identity.js

@@ -5,8 +5,24 @@ async function requestCredentials() {
     const token = process.env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
     if (url && token)
         return { url, token };
-    // A process started before the guest wrote its environment still finds it.
-    return fileCredentials();
+    // A process started without them (a server started before the guest wrote
+    // its environment, a sandbox whose guest software predates the variables)
+    // asks the host, which answers every running sandbox whatever its image or
+    // age, then the guest's file. Only inside a sandbox: elsewhere nothing is
+    // asked over the network.
+    if (!(await exists(sandboxMarker.path)))
+        return null;
+    return currentCredentials();
+}
+async function exists(path) {
+    try {
+        const { access } = await import("node:fs/promises");
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 async function fileCredentials() {
     try {

package/dist/products/builds.d.ts

@@ -86,8 +86,12 @@ export type ListBuilds = {
     name?: string;
     label?: string[];
     state?: BuildState[];
+    /** Only this connected repository's builds. */
+    repositoryId?: string;
+    /** Only builds of this commit, by its full sha. */
+    commit?: string;
 };
-export type ListRepositories = Omit<ListBuilds, "state"> & {
+export type ListRepositories = Omit<ListBuilds, "state" | "repositoryId" | "commit"> & {
     state?: Repository["state"][];
 };
 export type BuildLine = {
@@ -151,6 +155,12 @@ export declare function builds(t: Transport): {
         list: (query?: ListRepositories, options?: RequestOptions) => Promise<Page<Repository>>;
         update: (id: string, change: ChangeRepository, options?: RequestOptions) => Promise<Repository>;
         disconnect: (id: string, options?: RequestOptions) => Promise<Repository>;
+        /** A link to install Runtime's GitHub App, open for 15 minutes: a
+         * private repository builds once its owner installs it. */
+        installGithub: (options?: RequestOptions) => Promise<{
+            url: string;
+            expiresAt: string;
+        }>;
     };
 };
 export {};

package/dist/products/builds.js

@@ -222,6 +222,13 @@ export function builds(t) {
                 path: `/v1/repositories/${encodeURIComponent(id)}`,
                 ...options,
             }),
+            /** A link to install Runtime's GitHub App, open for 15 minutes: a
+             * private repository builds once its owner installs it. */
+            installGithub: (options) => t.json({
+                method: "POST",
+                path: "/v1/repositories/github:install",
+                ...options,
+            }),
         },
     };
 }

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.17.2";
+export declare const VERSION = "0.18.0";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs

package/dist/transport.js

@@ -1,7 +1,7 @@
 import { ConnectionError, DELIBERATE, errorFor, NOTHING_RAN, RuntimeError, WAITS_FOR_ROOM, } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
 import { warningText } from "./product-renames.js";
-export const VERSION = "0.17.2";
+export const VERSION = "0.18.0";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs

package/dist/vercel/errors.d.ts

@@ -45,7 +45,7 @@ export declare function translate(error: unknown, sandboxName?: string): unknown
 export declare function guard<T>(work: () => Promise<T>, sandboxName?: string): Promise<T>;
 /** A node:fs-style error, as Vercel's `sandbox.fs` throws. */
 export declare function fsError(code: "ENOENT" | "EEXIST" | "EISDIR" | "ENOTDIR" | "EACCES" | "ENOTEMPTY" | "EINVAL", syscall: string, path: string): Error & {
-    code: "ENOENT" | "ENOTDIR" | "EEXIST" | "EISDIR" | "EACCES" | "ENOTEMPTY" | "EINVAL";
+    code: "ENOENT" | "EEXIST" | "ENOTDIR" | "EISDIR" | "EACCES" | "ENOTEMPTY" | "EINVAL";
     errno: number;
     syscall: string;
     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",