@meltemi/diagrams-cli 0.0.0-stage → 1.9.0

package/dist/cloud-command.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The cloud commands (`cli-cloud`): one table of names to commands, and the dispatcher that gives
+ * each the same context, keeps tokens out of everything it prints and turns a `CloudError` into a
+ * line on standard error and an exit code (1, or 3 when the person has to run `login`).
+ *
+ * Adding a command is a file with a `CloudCommand` (`cloud-context.ts` has the helpers: `openCloud`
+ * for the host, the token and the client, `usageError`) and one line in `CLOUD_COMMANDS`; `cli.ts`
+ * and the help need nothing else but the words in `messages/`.
+ */
+import type { Locale } from "@meltemi/diagrams-i18n";
+import { type CloudCommand, type CloudContext, type CloudHooks } from "./cloud-context.js";
+/** The cloud commands by name. */
+declare const CLOUD_COMMANDS: {
+    readonly login: CloudCommand;
+    readonly push: CloudCommand;
+    readonly pull: CloudCommand;
+    readonly logout: CloudCommand;
+    readonly whoami: CloudCommand;
+    readonly projects: CloudCommand;
+    readonly publish: CloudCommand;
+};
+export type CloudCommandName = keyof typeof CLOUD_COMMANDS;
+/** The names of the cloud commands. */
+export declare const CLOUD_COMMAND_NAMES: CloudCommandName[];
+/** Whether a command name is one of the cloud commands. */
+export declare function isCloudCommand(name: string): name is CloudCommandName;
+/** What the dispatcher needs from the command line: its streams, its environment and its hooks. */
+export interface CloudCommandIo {
+    /** The command line's name, `meltemi-diagrams`. */
+    readonly name: string;
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    readonly cwd: string;
+    readonly display: (path: string) => string;
+    readonly toolVersion: string;
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    readonly ask?: ((question: string) => Promise<string>) | undefined;
+    readonly stdin?: (() => Promise<string>) | undefined;
+    readonly cloud?: CloudHooks | undefined;
+    /** The language of the files a command writes: `--lang`, when given (never the machine's). */
+    readonly locale?: Locale | undefined;
+}
+/**
+ * The context of a command, from the command line's streams and environment: its output goes
+ * through `redactSecrets`, so a token that an answer, a file or an error carried is shown as
+ * `mdg_…`. `cloudCommand` makes one for each cloud command; a command that is not one of them but
+ * talks to the service (`review --base cloud`) makes its own with `command` set to its name.
+ */
+export declare function cloudContext(command: string, io: CloudCommandIo): CloudContext;
+/**
+ * Runs a cloud command. A `CloudError` it throws is printed as `<name> <command>: <code>: <sentence>`
+ * on standard error (`reportCloudError`) and its exit code is returned.
+ */
+export declare function cloudCommand(command: CloudCommandName, args: readonly string[], io: CloudCommandIo): Promise<number>;
+export {};
+//# sourceMappingURL=cloud-command.d.ts.map

package/dist/cloud-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-command.d.ts","sourceRoot":"","sources":["../src/cloud-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAS5B,kCAAkC;AAClC,QAAA,MAAM,cAAc;;;;;;;;CAQuC,CAAC;AAE5D,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,cAAc,CAAC;AAE3D,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,EAAkC,gBAAgB,EAAE,CAAC;AAErF,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAErE;AAED,mGAAmG;AACnG,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,YAAY,CAyB9E;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,cAAc,GACjB,OAAO,CAAC,MAAM,CAAC,CAQjB"}

package/dist/cloud-command.js

@@ -0,0 +1,81 @@
+/**
+ * The cloud commands (`cli-cloud`): one table of names to commands, and the dispatcher that gives
+ * each the same context, keeps tokens out of everything it prints and turns a `CloudError` into a
+ * line on standard error and an exit code (1, or 3 when the person has to run `login`).
+ *
+ * Adding a command is a file with a `CloudCommand` (`cloud-context.ts` has the helpers: `openCloud`
+ * for the host, the token and the client, `usageError`) and one line in `CLOUD_COMMANDS`; `cli.ts`
+ * and the help need nothing else but the words in `messages/`.
+ */
+import { loginCommand, logoutCommand, whoamiCommand } from "./auth-command.js";
+import { reportCloudError, } from "./cloud-context.js";
+import { CloudError } from "./cloud-errors.js";
+import { CredentialsStore } from "./credentials.js";
+import { projectsCommand } from "./projects-command.js";
+import { publishCommand } from "./publish-command.js";
+import { pullCommand } from "./pull-command.js";
+import { pushCommand } from "./push-command.js";
+import { redactSecrets } from "./redact.js";
+/** The cloud commands by name. */
+const CLOUD_COMMANDS = {
+    login: loginCommand,
+    push: pushCommand,
+    pull: pullCommand,
+    logout: logoutCommand,
+    whoami: whoamiCommand,
+    projects: projectsCommand,
+    publish: publishCommand,
+};
+/** The names of the cloud commands. */
+export const CLOUD_COMMAND_NAMES = Object.keys(CLOUD_COMMANDS);
+/** Whether a command name is one of the cloud commands. */
+export function isCloudCommand(name) {
+    return Object.hasOwn(CLOUD_COMMANDS, name);
+}
+/**
+ * The context of a command, from the command line's streams and environment: its output goes
+ * through `redactSecrets`, so a token that an answer, a file or an error carried is shown as
+ * `mdg_…`. `cloudCommand` makes one for each cloud command; a command that is not one of them but
+ * talks to the service (`review --base cloud`) makes its own with `command` set to its name.
+ */
+export function cloudContext(command, io) {
+    const env = io.env ?? process.env;
+    const hooks = io.cloud ?? {};
+    const clean = (write) => (text) => write(redactSecrets(text, env));
+    return {
+        name: io.name,
+        command,
+        stdout: clean(io.stdout),
+        stderr: clean(io.stderr),
+        cwd: io.cwd,
+        display: io.display,
+        env,
+        toolVersion: io.toolVersion,
+        ...(io.ask ? { ask: io.ask } : {}),
+        ...(io.stdin ? { stdin: io.stdin } : {}),
+        ...(io.locale ? { locale: io.locale } : {}),
+        hooks,
+        credentials: new CredentialsStore({
+            env,
+            ...(hooks.platform ? { platform: hooks.platform } : {}),
+            ...(hooks.home ? { home: hooks.home } : {}),
+        }),
+        used: {},
+    };
+}
+/**
+ * Runs a cloud command. A `CloudError` it throws is printed as `<name> <command>: <code>: <sentence>`
+ * on standard error (`reportCloudError`) and its exit code is returned.
+ */
+export async function cloudCommand(command, args, io) {
+    const context = cloudContext(command, io);
+    try {
+        return await CLOUD_COMMANDS[command](args, context);
+    }
+    catch (error) {
+        if (error instanceof CloudError)
+            return reportCloudError(error, context);
+        throw error;
+    }
+}
+//# sourceMappingURL=cloud-command.js.map

package/dist/cloud-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-command.js","sourceRoot":"","sources":["../src/cloud-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,gBAAgB,GAIjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,kCAAkC;AAClC,MAAM,cAAc,GAAG;IACrB,KAAK,EAAE,YAAY;IACnB,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,QAAQ,EAAE,eAAe;IACzB,OAAO,EAAE,cAAc;CACkC,CAAC;AAI5D,uCAAuC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,CAAuB,CAAC;AAErF,2DAA2D;AAC3D,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC;AAmBD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,EAAkB;IAC9D,MAAM,GAAG,GAAG,EAAE,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAClC,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,CAAC,KAA6B,EAAE,EAAE,CAAC,CAAC,IAAY,EAAE,EAAE,CAChE,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IAClC,OAAO;QACL,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,OAAO;QACP,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC;QACxB,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC;QACxB,GAAG,EAAE,EAAE,CAAC,GAAG;QACX,OAAO,EAAE,EAAE,CAAC,OAAO;QACnB,GAAG;QACH,WAAW,EAAE,EAAE,CAAC,WAAW;QAC3B,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,KAAK;QACL,WAAW,EAAE,IAAI,gBAAgB,CAAC;YAChC,GAAG;YACH,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5C,CAAC;QACF,IAAI,EAAE,EAAE;KACT,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAyB,EACzB,IAAuB,EACvB,EAAkB;IAElB,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,OAAO,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,UAAU;YAAE,OAAO,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzE,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/cloud-context.d.ts

@@ -0,0 +1,106 @@
+/**
+ * What every cloud command shares (`cli-cloud`): the context the dispatcher gives it, the way it
+ * finds its host and its token, how it reports a usage error, and how a failure reads in the
+ * interface language. A command is `(args, context) => Promise<number>` in a file of its own,
+ * registered in `cloud-command.ts`.
+ *
+ * ```ts
+ * export const pushCommand: CloudCommand = async (args, context) => {
+ *   const { values, positionals } = parseArgs(...); // usageError(context, error, help) on a throw
+ *   const { host, client } = openCloud(context, { host: values.host, manifestHost: manifest.cloud?.host });
+ *   const files = await client.files(projectId);
+ *   ...
+ *   return EXIT_OK;
+ * };
+ * ```
+ *
+ * A command reports a failure by throwing a `CloudError` (`cloud-errors.ts`); the dispatcher prints
+ * it as `<name> <command>: <code>: <sentence>` on standard error and exits with the error's code.
+ */
+import type { Locale } from "@meltemi/diagrams-i18n";
+import { CloudClient, type Fetch } from "./cloud-client.js";
+import { CloudError } from "./cloud-errors.js";
+import { CredentialsStore, type ResolvedToken } from "./credentials.js";
+/** What a test replaces: the network, the browser, the clock of the wait, the configuration folder. */
+export interface CloudHooks {
+    /** Replaces `fetch`. */
+    readonly fetch?: Fetch;
+    /** Opens an address in the browser; rejects when it cannot. */
+    readonly openBrowser?: (url: string) => Promise<void> | void;
+    /** Milliseconds `login` waits for the approval; five minutes by default. */
+    readonly loginTimeoutMs?: number;
+    /** The platform and home folder the credentials folder is derived from. */
+    readonly platform?: NodeJS.Platform;
+    readonly home?: string;
+}
+export interface CloudContext {
+    /** The command line's name, `meltemi-diagrams`, for messages that name a command to run. */
+    readonly name: string;
+    /** The cloud command being run: `login`, `push`, … */
+    readonly command: string;
+    /** Output, with API tokens already replaced by `mdg_…`. */
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    readonly cwd: string;
+    /** A path as printed: relative to the working folder. */
+    readonly display: (path: string) => string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly toolVersion: string;
+    /** Asks a question in a terminal; absent when nobody can answer (then refuse unless `--force`). */
+    readonly ask?: (question: string) => Promise<string>;
+    /** Reads standard input (for `login --token`); absent when the host gave none. */
+    readonly stdin?: () => Promise<string>;
+    /** The language of the files the command writes: `--lang`, when given (never the machine's). */
+    readonly locale?: Locale;
+    readonly hooks: CloudHooks;
+    readonly credentials: CredentialsStore;
+    /** What the command has settled on so far, so that a failure can name it. */
+    readonly used: {
+        host?: string;
+        project?: string;
+    };
+}
+/** A cloud command: its arguments after its name, and the exit code. */
+export type CloudCommand = (args: readonly string[], context: CloudContext) => Promise<number>;
+/** A client for a host, with the token given (none for the calls that need none). */
+export declare function newClient(context: CloudContext, host: string, token?: string): CloudClient;
+/**
+ * The host of a command: `--host`, else `MELTEMI_HOST`, else the default (never a manifest's). When
+ * `manifestHost` is given (`project.json`'s `cloud.host`) and is another host, it fails with
+ * `cloud.host-mismatch` before anything is sent.
+ */
+export declare function cloudHost(context: CloudContext, options?: {
+    readonly host?: string | undefined;
+    readonly manifestHost?: string | null | undefined;
+}): string;
+/** A command's connection to the service. */
+export interface CloudSession {
+    readonly host: string;
+    readonly client: CloudClient;
+    /** Where the token came from (`MELTEMI_TOKEN`, or the credentials file). */
+    readonly token: ResolvedToken;
+}
+/**
+ * The host and a client with its token, for a command that needs to be signed in: resolves the host
+ * (`cloudHost`), then the token (`MELTEMI_TOKEN`, else the stored entry for that host); with none,
+ * `cloud.not-signed-in` (exit code 3, "run login"). Nothing has been sent when it returns or throws.
+ */
+export declare function openCloud(context: CloudContext, options?: {
+    readonly host?: string | undefined;
+    readonly manifestHost?: string | null | undefined;
+}): CloudSession;
+/** Prints a usage error with the command's usage, and the exit code 2 (`parseArgs` threw). */
+export declare function usageError(context: CloudContext, error: unknown, help: string): number;
+/** Prints a usage message with the command's usage, and the exit code 2. */
+export declare function usage(context: CloudContext, message: string, help: string): number;
+/**
+ * Prints a failure on standard error as `<name> <command>: <code>: <sentence>` and answers the exit
+ * code it carries (3 when the person has to run `login`, else 1).
+ */
+export declare function reportCloudError(error: CloudError, context: CloudContext): number;
+/**
+ * A failure as a person reads it: the stable code, then a sentence in the interface language when
+ * the code is one the command line knows, else the service's own English message.
+ */
+export declare function describeCloudError(error: CloudError, context: CloudContext): string;
+//# sourceMappingURL=cloud-context.d.ts.map

package/dist/cloud-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-context.d.ts","sourceRoot":"","sources":["../src/cloud-context.ts"],"names":[],"mappings":"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"}

package/dist/cloud-context.js

@@ -0,0 +1,185 @@
+/**
+ * What every cloud command shares (`cli-cloud`): the context the dispatcher gives it, the way it
+ * finds its host and its token, how it reports a usage error, and how a failure reads in the
+ * interface language. A command is `(args, context) => Promise<number>` in a file of its own,
+ * registered in `cloud-command.ts`.
+ *
+ * ```ts
+ * export const pushCommand: CloudCommand = async (args, context) => {
+ *   const { values, positionals } = parseArgs(...); // usageError(context, error, help) on a throw
+ *   const { host, client } = openCloud(context, { host: values.host, manifestHost: manifest.cloud?.host });
+ *   const files = await client.files(projectId);
+ *   ...
+ *   return EXIT_OK;
+ * };
+ * ```
+ *
+ * A command reports a failure by throwing a `CloudError` (`cloud-errors.ts`); the dispatcher prints
+ * it as `<name> <command>: <code>: <sentence>` on standard error and exits with the error's code.
+ */
+import { formatSize } from "./build-command.js";
+import { argumentsError, messages } from "./messages/index.js";
+import { CloudClient } from "./cloud-client.js";
+import { CloudError, EXIT_USAGE } from "./cloud-errors.js";
+import { describeProjectError } from "./project-errors.js";
+import { CredentialsStore, checkManifestHost, resolveHost, } from "./credentials.js";
+/** A client for a host, with the token given (none for the calls that need none). */
+export function newClient(context, host, token) {
+    return new CloudClient({
+        host,
+        token,
+        userAgent: `${context.name}/${context.toolVersion}`,
+        ...(context.hooks.fetch ? { fetch: context.hooks.fetch } : {}),
+    });
+}
+/**
+ * The host of a command: `--host`, else `MELTEMI_HOST`, else the default (never a manifest's). When
+ * `manifestHost` is given (`project.json`'s `cloud.host`) and is another host, it fails with
+ * `cloud.host-mismatch` before anything is sent.
+ */
+export function cloudHost(context, options = {}) {
+    const host = resolveHost({ flag: options.host, env: context.env });
+    context.used.host = host;
+    checkManifestHost(host, options.manifestHost);
+    return host;
+}
+/**
+ * The host and a client with its token, for a command that needs to be signed in: resolves the host
+ * (`cloudHost`), then the token (`MELTEMI_TOKEN`, else the stored entry for that host); with none,
+ * `cloud.not-signed-in` (exit code 3, "run login"). Nothing has been sent when it returns or throws.
+ */
+export function openCloud(context, options = {}) {
+    const host = cloudHost(context, options);
+    const token = context.credentials.resolveToken(host, context.env);
+    if (token === undefined) {
+        throw new CloudError("cloud.not-signed-in", `There is no token for ${host}.`, {
+            details: { host },
+        });
+    }
+    return { host, client: newClient(context, host, token.token), token };
+}
+/** Prints a usage error with the command's usage, and the exit code 2 (`parseArgs` threw). */
+export function usageError(context, error, help) {
+    return usage(context, argumentsError(error), help);
+}
+/** Prints a usage message with the command's usage, and the exit code 2. */
+export function usage(context, message, help) {
+    context.stderr(`${context.name} ${context.command}: ${message}\n\n${help}`);
+    return EXIT_USAGE;
+}
+/**
+ * Prints a failure on standard error as `<name> <command>: <code>: <sentence>` and answers the exit
+ * code it carries (3 when the person has to run `login`, else 1).
+ */
+export function reportCloudError(error, context) {
+    context.stderr(`${context.name} ${context.command}: ${describeCloudError(error, context)}\n`);
+    return error.exitCode;
+}
+/** What a `details` entry is, as text. */
+const text = (value, fallback) => typeof value === "string" && value !== "" ? value : fallback;
+/**
+ * A failure as a person reads it: the stable code, then a sentence in the interface language when
+ * the code is one the command line knows, else the service's own English message.
+ */
+export function describeCloudError(error, context) {
+    const t = messages().cloud.errors;
+    const host = text(error.details["host"], context.used.host ?? "the service");
+    const path = text(error.details["path"], "");
+    const reason = text(error.details["reason"], error.message);
+    const sentence = (() => {
+        switch (error.code) {
+            case "cloud.host-mismatch":
+                return t.hostMismatch(text(error.details["manifestHost"], "?"), host);
+            case "cloud.insecure-host":
+                return t.insecureHost(host);
+            case "cloud.host-invalid":
+                return t.hostInvalid(host);
+            case "cloud.unreachable":
+                return t.unreachable(host, reason);
+            case "cloud.timeout":
+                return t.timeout(host);
+            case "cloud.response-too-large":
+                return t.tooLarge(host);
+            case "cloud.redirect":
+                return t.redirect(host, error.status);
+            case "cloud.bad-response":
+                return t.badResponse(host, error.status);
+            case "cloud.not-signed-in":
+                return t.notSignedIn(context.name, host);
+            case "token.invalid":
+            case "auth.required":
+                return t.tokenRefused(context.name, host);
+            case "credentials.corrupt":
+                return t.credentialsCorrupt(path, reason);
+            case "credentials.unreadable":
+                return t.credentialsUnreadable(path, reason);
+            case "credentials.unwritable":
+                return t.credentialsUnwritable(path, reason);
+            case "cli.invalid":
+                return t.cliInvalid;
+            case "cli.rate":
+                return t.cliRate(error.retryAfter ?? 60);
+            case "quota.tokens":
+                return t.quotaTokens;
+            case "login.timeout":
+                return t.loginTimeout;
+            case "login.state-mismatch":
+                return t.stateMismatch;
+            case "login.environment-token":
+                return t.environmentToken;
+            case "login.token-input":
+                return t.tokenInput;
+            case "login.no-token":
+                return t.noToken;
+            case "login.not-a-token":
+                return t.notAToken;
+            case "login.not-stored":
+                return t.notStored(reason);
+            case "login.not-stored-not-revoked":
+                return t.notStoredNotRevoked(reason);
+            case "login.listener":
+                return t.listener(reason);
+            case "logout.not-revoked":
+                return t.notRevoked(host, reason, path);
+            case "cloud.no-project":
+                return t.noProject(context.name);
+            case "pull.unsafe-path":
+                return t.unsafePath(path);
+            case "version.not-found":
+                return t.versionNotFound(text(String(error.details["version"] ?? ""), "that was asked for"));
+            case "project.not-found":
+                return t.projectNotFound(text(error.details["project"], context.used.project ?? "?"));
+            case "access.denied":
+                return t.accessDenied;
+            case "handle.taken":
+                return t.handleTaken(text(error.details["handle"], "chosen"));
+            case "handle.locked":
+                // The handle the account has, which cannot change; else the one asked for.
+                return t.handleLocked(text(error.details["current"], text(error.details["handle"], "?")));
+            case "handle.invalid":
+                return t.handleInvalid(text(error.details["handle"], "that"));
+            case "handle.required":
+                return t.handleRequired(context.name);
+            case "publish.handle-in-page":
+                return t.handleInPage(text(error.details["handle"], "you want"));
+            case "publish.too-large":
+                return t.publishTooLarge(typeof error.details["bytes"] === "number"
+                    ? formatSize(error.details["bytes"])
+                    : undefined);
+            case "publish.rate":
+                return t.publishRate(error.retryAfter ?? 3600);
+            case "publish.taken":
+                return t.publishTaken(text(error.details["slug"], "that name"));
+            case "publish.not-published":
+                return t.notPublished(text(error.details["slug"], "that name"));
+            case "publish.empty":
+                return t.publishEmpty;
+            case "publish.errors":
+                return t.publishErrors;
+            default:
+                return describeProjectError(error) ?? error.message;
+        }
+    })();
+    return `${error.code}: ${sentence}`;
+}
+//# sourceMappingURL=cloud-context.js.map

package/dist/cloud-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-context.js","sourceRoot":"","sources":["../src/cloud-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAc,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GAEZ,MAAM,kBAAkB,CAAC;AA2C1B,qFAAqF;AACrF,MAAM,UAAU,SAAS,CAAC,OAAqB,EAAE,IAAY,EAAE,KAAc;IAC3E,OAAO,IAAI,WAAW,CAAC;QACrB,IAAI;QACJ,KAAK;QACL,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE;QACnD,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,OAAqB,EACrB,UAGI,EAAE;IAEN,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACnE,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACzB,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAUD;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,OAAqB,EACrB,UAGI,EAAE;IAEN,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAClE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,qBAAqB,EAAE,yBAAyB,IAAI,GAAG,EAAE;YAC5E,OAAO,EAAE,EAAE,IAAI,EAAE;SAClB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;AACxE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,UAAU,CAAC,OAAqB,EAAE,KAAc,EAAE,IAAY;IAC5E,OAAO,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,KAAK,CAAC,OAAqB,EAAE,OAAe,EAAE,IAAY;IACxE,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,OAAO,IAAI,EAAE,CAAC,CAAC;IAC5E,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB,EAAE,OAAqB;IACvE,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,OAAO,KAAK,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9F,OAAO,KAAK,CAAC,QAAQ,CAAC;AACxB,CAAC;AAED,0CAA0C;AAC1C,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,QAAgB,EAAU,EAAE,CACxD,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAE/D;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAiB,EAAE,OAAqB;IACzE,MAAM,CAAC,GAAG,QAAQ,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,aAAa,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAE;QAC7B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,qBAAqB;gBACxB,OAAO,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;YACxE,KAAK,qBAAqB;gBACxB,OAAO,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAC9B,KAAK,oBAAoB;gBACvB,OAAO,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YAC7B,KAAK,mBAAmB;gBACtB,OAAO,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACrC,KAAK,eAAe;gBAClB,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACzB,KAAK,0BAA0B;gBAC7B,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC1B,KAAK,gBAAgB;gBACnB,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YACxC,KAAK,oBAAoB;gBACvB,OAAO,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YAC3C,KAAK,qBAAqB;gBACxB,OAAO,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3C,KAAK,eAAe,CAAC;YACrB,KAAK,eAAe;gBAClB,OAAO,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC5C,KAAK,qBAAqB;gBACxB,OAAO,CAAC,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC5C,KAAK,wBAAwB;gBAC3B,OAAO,CAAC,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC/C,KAAK,wBAAwB;gBAC3B,OAAO,CAAC,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC/C,KAAK,aAAa;gBAChB,OAAO,CAAC,CAAC,UAAU,CAAC;YACtB,KAAK,UAAU;gBACb,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;YAC3C,KAAK,cAAc;gBACjB,OAAO,CAAC,CAAC,WAAW,CAAC;YACvB,KAAK,eAAe;gBAClB,OAAO,CAAC,CAAC,YAAY,CAAC;YACxB,KAAK,sBAAsB;gBACzB,OAAO,CAAC,CAAC,aAAa,CAAC;YACzB,KAAK,yBAAyB;gBAC5B,OAAO,CAAC,CAAC,gBAAgB,CAAC;YAC5B,KAAK,mBAAmB;gBACtB,OAAO,CAAC,CAAC,UAAU,CAAC;YACtB,KAAK,gBAAgB;gBACnB,OAAO,CAAC,CAAC,OAAO,CAAC;YACnB,KAAK,mBAAmB;gBACtB,OAAO,CAAC,CAAC,SAAS,CAAC;YACrB,KAAK,kBAAkB;gBACrB,OAAO,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAC7B,KAAK,8BAA8B;gBACjC,OAAO,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;YACvC,KAAK,gBAAgB;gBACnB,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC5B,KAAK,oBAAoB;gBACvB,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;YAC1C,KAAK,kBAAkB;gBACrB,OAAO,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACnC,KAAK,kBAAkB;gBACrB,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAC5B,KAAK,mBAAmB;gBACtB,OAAO,CAAC,CAAC,eAAe,CACtB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,EAAE,oBAAoB,CAAC,CACnE,CAAC;YACJ,KAAK,mBAAmB;gBACtB,OAAO,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC;YACxF,KAAK,eAAe;gBAClB,OAAO,CAAC,CAAC,YAAY,CAAC;YACxB,KAAK,cAAc;gBACjB,OAAO,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;YAChE,KAAK,eAAe;gBAClB,2EAA2E;gBAC3E,OAAO,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;YAC5F,KAAK,gBAAgB;gBACnB,OAAO,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;YAChE,KAAK,iBAAiB;gBACpB,OAAO,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACxC,KAAK,wBAAwB;gBAC3B,OAAO,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;YACnE,KAAK,mBAAmB;gBACtB,OAAO,CAAC,CAAC,eAAe,CACtB,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,QAAQ;oBACxC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;oBACpC,CAAC,CAAC,SAAS,CACd,CAAC;YACJ,KAAK,cAAc;gBACjB,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC;YACjD,KAAK,eAAe;gBAClB,OAAO,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC;YAClE,KAAK,uBAAuB;gBAC1B,OAAO,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC;YAClE,KAAK,eAAe;gBAClB,OAAO,CAAC,CAAC,YAAY,CAAC;YACxB,KAAK,gBAAgB;gBACnB,OAAO,CAAC,CAAC,aAAa,CAAC;YACzB;gBACE,OAAO,oBAAoB,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC;QACxD,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IACL,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;AACtC,CAAC"}

package/dist/cloud-errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The failures of the cloud commands (`cli-cloud`): one typed error for the service's answers, for
+ * what the command line refuses before it asks, and for the credentials file. The `code` is the
+ * stable name (the service's own for an answer, `cloud.*`, `credentials.*` and `login.*` for the
+ * command line's); the `message` is English, never holds a token, and is what an unknown code is
+ * printed with. `describeCloudError` (`cloud-command.ts`) turns the known codes into the
+ * interface language.
+ */
+/** Exit codes of the cloud commands: 0 done, 1 failed, 2 usage error, 3 sign in. */
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_USAGE = 2;
+/** Not signed in, or the service refused the token: run `mdg login`. */
+export declare const EXIT_AUTH = 3;
+export interface CloudErrorOptions {
+    /** The HTTP status of the service's answer; 0 when there was none or the refusal is local. */
+    readonly status?: number;
+    /** What the code carries: the room's `revision` of a `revision.mismatch`, a host, a path. */
+    readonly details?: Readonly<Record<string, unknown>>;
+    /** Seconds the service asked to wait (`Retry-After`). */
+    readonly retryAfter?: number;
+    /** Overrides the exit code the code implies (3 for the sign-in codes, else 1). */
+    readonly exitCode?: number;
+}
+export declare class CloudError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details: Readonly<Record<string, unknown>>;
+    readonly retryAfter: number | undefined;
+    readonly exitCode: number;
+    constructor(code: string, message: string, options?: CloudErrorOptions);
+    /** The room's revision a `revision.mismatch` carries, when it is a number. */
+    get revision(): number | undefined;
+}
+/** Whether an error is a `CloudError`, with the code given when there is one. */
+export declare function isCloudError(error: unknown, code?: string): error is CloudError;
+//# sourceMappingURL=cloud-errors.d.ts.map

package/dist/cloud-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-errors.d.ts","sourceRoot":"","sources":["../src/cloud-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oFAAoF;AACpF,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,wEAAwE;AACxE,eAAO,MAAM,SAAS,IAAI,CAAC;AAS3B,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,UAAW,SAAQ,KAAK;IAOjC,QAAQ,CAAC,IAAI,EAAE,MAAM;IANvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGf,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB;IAUjC,8EAA8E;IAC9E,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAGjC;CACF;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/E"}

package/dist/cloud-errors.js

@@ -0,0 +1,46 @@
+/**
+ * The failures of the cloud commands (`cli-cloud`): one typed error for the service's answers, for
+ * what the command line refuses before it asks, and for the credentials file. The `code` is the
+ * stable name (the service's own for an answer, `cloud.*`, `credentials.*` and `login.*` for the
+ * command line's); the `message` is English, never holds a token, and is what an unknown code is
+ * printed with. `describeCloudError` (`cloud-command.ts`) turns the known codes into the
+ * interface language.
+ */
+/** Exit codes of the cloud commands: 0 done, 1 failed, 2 usage error, 3 sign in. */
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+/** Not signed in, or the service refused the token: run `mdg login`. */
+export const EXIT_AUTH = 3;
+/** Codes that mean the person has to sign in: the service's two and the command line's own. */
+const AUTH_CODES = new Set([
+    "token.invalid",
+    "auth.required",
+    "cloud.not-signed-in",
+]);
+export class CloudError extends Error {
+    code;
+    status;
+    details;
+    retryAfter;
+    exitCode;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.code = code;
+        this.name = "CloudError";
+        this.status = options.status ?? 0;
+        this.details = options.details ?? {};
+        this.retryAfter = options.retryAfter;
+        this.exitCode = options.exitCode ?? (AUTH_CODES.has(code) ? EXIT_AUTH : EXIT_FAILED);
+    }
+    /** The room's revision a `revision.mismatch` carries, when it is a number. */
+    get revision() {
+        const revision = this.details["revision"];
+        return typeof revision === "number" ? revision : undefined;
+    }
+}
+/** Whether an error is a `CloudError`, with the code given when there is one. */
+export function isCloudError(error, code) {
+    return error instanceof CloudError && (code === undefined || error.code === code);
+}
+//# sourceMappingURL=cloud-errors.js.map

package/dist/cloud-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-errors.js","sourceRoot":"","sources":["../src/cloud-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oFAAoF;AACpF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AACzB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,wEAAwE;AACxE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAE3B,+FAA+F;AAC/F,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IAC9C,eAAe;IACf,eAAe;IACf,qBAAqB;CACtB,CAAC,CAAC;AAaH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAOxB;IANF,MAAM,CAAS;IACf,OAAO,CAAoC;IAC3C,UAAU,CAAqB;IAC/B,QAAQ,CAAS;IAE1B,YACW,IAAY,EACrB,OAAe,EACf,UAA6B,EAAE;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,SAAI,GAAJ,IAAI,CAAQ;QAKrB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACvF,CAAC;IAED,8EAA8E;IAC9E,IAAI,QAAQ;QACV,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC1C,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7D,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,IAAa;IACxD,OAAO,KAAK,YAAY,UAAU,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACpF,CAAC"}

package/dist/cloud-host.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A cloud project as a `ProjectHost` (`cli-cloud`, "Projects and review against the cloud"): what
+ * `review --base cloud[:<n>]` compares the folder with, as `gitRevisionHost` is what `review
+ * --base <revision>` compares it with.
+ *
+ * A `ProjectHost` is synchronous, so the cloud is read once, up front: the project's files (or a
+ * version's) and the images and fonts they reference, each blob once. Every path the service
+ * answers then goes through the path rule of the cloud (`isCleanPath`) and must resolve inside the
+ * project's root; one that does not is `pull.unsafe-path` and nothing is compared. The only paths
+ * left out without a word are the losers of a name collision (`<path>~<id>`, listed in the
+ * answer's `collisions`): the service keeps them out of copies and restores for the same reason.
+ *
+ * The host is rooted at the local project root, like the git host is rooted at the repository:
+ * `<root>/<path>` answers the fetched text or bytes and `readDirectory` is made from the path set.
+ */
+import { type ProjectHost } from "@meltemi/diagrams-project";
+import type { CloudClient } from "./cloud-client.js";
+/** The files of a cloud project as the service answered them, before any host is made of them. */
+export interface CloudSnapshot {
+    /** The room's revision of a snapshot of the current files; undefined for a version. */
+    readonly revision: number | undefined;
+    /** The version the snapshot is of; undefined for the current files. */
+    readonly version: number | undefined;
+    /** Path to text. */
+    readonly files: ReadonlyMap<string, string>;
+    /** Path to the hash and the bytes of an image or a font. */
+    readonly binaries: ReadonlyMap<string, {
+        readonly hash: string;
+        readonly bytes: Uint8Array;
+    }>;
+    /** Collision losers (`<path>~<id>`) that were left out. */
+    readonly skipped: readonly string[];
+}
+/**
+ * Whether a path the cloud answered is NOT safe to put under `root` by itself, with the checks
+ * `pull` makes (`cloud-paths.ts`): it breaks the cloud's path rule, a name of it could not be kept
+ * on Windows (a device name such as `con` or `com1.txt`, a name that ends with a dot or a space), or
+ * joined to the root it leaves it (or is the root itself). What only a set of paths can show
+ * (`setProblems`) is checked by `checkCloudPaths`.
+ */
+export declare function unsafeCloudPath(root: string, path: string): boolean;
+/**
+ * Fails with `pull.unsafe-path` naming the first of `paths` that is not safe under `root`: one that
+ * `unsafeCloudPath` refuses, or that cannot be written beside the others, because it differs from
+ * another only in letter case (one overwrites the other on Windows and macOS) or is a file where
+ * another path needs a folder. The path is named as `pull` names it, escaped (`printablePath`), as it
+ * is the cloud's to choose and the terminal is the person's.
+ */
+export declare function checkCloudPaths(root: string, paths: Iterable<string>): void;
+/**
+ * Reads a cloud project once: its current files, or version `version`'s, and the blobs they
+ * reference. `root` is the folder the paths are checked against (`pull.unsafe-path`, before any
+ * blob is fetched). An unknown version is `version.not-found` naming it; an unknown project,
+ * `project.not-found`.
+ */
+export declare function fetchCloudSnapshot(client: CloudClient, options: {
+    readonly project: string;
+    readonly root: string;
+    readonly version?: number;
+}): Promise<CloudSnapshot>;
+/** The host of a snapshot, rooted at `root`: `<root>/<path>` is the file the cloud holds there. */
+export declare function cloudSnapshotHost(root: string, snapshot: CloudSnapshot): ProjectHost;
+/**
+ * The host of a cloud project (`project`, its current files or those of `version`) rooted at the
+ * local project root `root`, filled by one prefetch (`fetchCloudSnapshot`).
+ */
+export declare function cloudHost(client: CloudClient, options: {
+    readonly project: string;
+    readonly root: string;
+    readonly version?: number;
+}): Promise<ProjectHost>;
+//# sourceMappingURL=cloud-host.d.ts.map

package/dist/cloud-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-host.d.ts","sourceRoot":"","sources":["../src/cloud-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAA8B,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAarD,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IAC9F,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAY3E;AA8BD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACtF,OAAO,CAAC,aAAa,CAAC,CAwCxB;AAED,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,WAAW,CAKpF;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACtF,OAAO,CAAC,WAAW,CAAC,CAEtB"}