@meltemi/diagrams-cli 0.0.0-stage → 1.9.0

package/dist/cloud-host.js

@@ -0,0 +1,129 @@
+/**
+ * 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 { createMemoryHost, joinPath } from "@meltemi/diagrams-project";
+import { collisionLosers, insideFolder, pathProblem, printablePath, setProblems, } from "./cloud-paths.js";
+import { CloudError, isCloudError } from "./cloud-errors.js";
+/** The most blobs fetched at once. */
+const BLOB_CONCURRENCY = 4;
+/**
+ * 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 function unsafeCloudPath(root, path) {
+    return pathProblem(path) !== undefined || insideFolder(root, path) === undefined;
+}
+/**
+ * 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 function checkCloudPaths(root, paths) {
+    const all = [...paths];
+    const together = setProblems(all.filter((path) => pathProblem(path) === undefined));
+    for (const path of all) {
+        if (!unsafeCloudPath(root, path) && !together.has(path))
+            continue;
+        const shown = printablePath(path);
+        throw new CloudError("pull.unsafe-path", `The cloud project holds ${JSON.stringify(shown)}, which is not a safe path inside the folder.`, { details: { path: shown } });
+    }
+}
+/** Runs `task` over `items`, at most `limit` at a time; the first failure is the one thrown. */
+async function pooled(items, limit, task) {
+    const results = new Array(items.length);
+    let next = 0;
+    let failure;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && next < items.length) {
+            const index = next++;
+            try {
+                results[index] = await task(items[index]);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    if (failed)
+        throw failure;
+    return results;
+}
+/**
+ * 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 async function fetchCloudSnapshot(client, options) {
+    const { project, root, version } = options;
+    let answer;
+    try {
+        answer =
+            version === undefined
+                ? await client.files(project)
+                : await client.readVersion(project, version);
+    }
+    catch (error) {
+        if (isCloudError(error, "version.not-found")) {
+            throw new CloudError(error.code, error.message, {
+                status: error.status,
+                details: { ...error.details, project, version },
+            });
+        }
+        throw error;
+    }
+    // The losers of a name collision (`<path>~<id>`) are display names: left out, as pull and push do.
+    const losers = collisionLosers([...Object.keys(answer.files), ...Object.keys(answer.binaries)], "collisions" in answer ? answer.collisions : []);
+    const files = new Map(Object.entries(answer.files).filter(([path]) => !losers.has(path)));
+    const hashes = new Map(Object.entries(answer.binaries).filter(([path]) => !losers.has(path)));
+    checkCloudPaths(root, [...files.keys(), ...hashes.keys()]);
+    const wanted = [...new Set(hashes.values())];
+    const fetched = await pooled(wanted, BLOB_CONCURRENCY, (hash) => client.blob(project, hash));
+    const bytesOf = new Map(wanted.map((hash, index) => [hash, fetched[index]]));
+    return {
+        revision: "revision" in answer ? answer.revision : undefined,
+        version,
+        files,
+        binaries: new Map([...hashes].map(([path, hash]) => [path, { hash, bytes: bytesOf.get(hash) }])),
+        skipped: [...new Set([...Object.keys(answer.files), ...Object.keys(answer.binaries)])].filter((path) => losers.has(path)),
+    };
+}
+/** The host of a snapshot, rooted at `root`: `<root>/<path>` is the file the cloud holds there. */
+export function cloudSnapshotHost(root, snapshot) {
+    const contents = {};
+    for (const [path, text] of snapshot.files)
+        contents[joinPath(root, path)] = text;
+    for (const [path, binary] of snapshot.binaries)
+        contents[joinPath(root, path)] = binary.bytes;
+    return createMemoryHost(contents);
+}
+/**
+ * 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 async function cloudHost(client, options) {
+    return cloudSnapshotHost(options.root, await fetchCloudSnapshot(client, options));
+}
+//# sourceMappingURL=cloud-host.js.map

package/dist/cloud-host.js.map

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

package/dist/cloud-manifest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `cloud` field of `project.json` (`cli-cloud`, "Push" and "Pull"): `{ "host": …, "project": … }`,
+ * written by `push --create` and `pull` through `setJsonObjectField`, which keeps the file's
+ * indentation, line endings and everything else byte for byte.
+ */
+/**
+ * The text of a manifest with its `cloud` field set to the service and the cloud project: replaced
+ * when it is there (and unchanged when it is already these values), else added after the last field.
+ * A byte order mark stays. Throws when the text is not a JSON object.
+ */
+export declare function withCloudField(text: string, host: string, project: string): string;
+//# sourceMappingURL=cloud-manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-manifest.d.ts","sourceRoot":"","sources":["../src/cloud-manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKlF"}

package/dist/cloud-manifest.js

@@ -0,0 +1,21 @@
+/**
+ * The `cloud` field of `project.json` (`cli-cloud`, "Push" and "Pull"): `{ "host": …, "project": … }`,
+ * written by `push --create` and `pull` through `setJsonObjectField`, which keeps the file's
+ * indentation, line endings and everything else byte for byte.
+ */
+import { setJsonObjectField } from "@meltemi/diagrams-editor";
+import { applyTextEdits } from "@meltemi/diagrams-language";
+/** The byte order mark, which a Windows editor may put in front of a JSON file. */
+const BYTE_ORDER_MARK = 0xfeff;
+/**
+ * The text of a manifest with its `cloud` field set to the service and the cloud project: replaced
+ * when it is there (and unchanged when it is already these values), else added after the last field.
+ * A byte order mark stays. Throws when the text is not a JSON object.
+ */
+export function withCloudField(text, host, project) {
+    const bom = text.charCodeAt(0) === BYTE_ORDER_MARK;
+    const body = bom ? text.slice(1) : text;
+    const edited = applyTextEdits(body, setJsonObjectField(body, "cloud", { host, project }));
+    return bom ? String.fromCharCode(BYTE_ORDER_MARK) + edited : edited;
+}
+//# sourceMappingURL=cloud-manifest.js.map

package/dist/cloud-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-manifest.js","sourceRoot":"","sources":["../src/cloud-manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,mFAAmF;AACnF,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAY,EAAE,OAAe;IACxE,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,eAAe,CAAC;IACnD,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAC1F,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AACtE,CAAC"}

package/dist/cloud-paths.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What a path of a cloud project must be before it may be written under a folder (`cli-cloud`,
+ * "Pull"): one rule for `pull` and for every command that reads a cloud project into a folder's
+ * place (`review --base cloud`).
+ *
+ * The cloud already refuses every path that breaks its path rule, so what arrives is what the
+ * service kept; the command line does not take that on trust, because the folder is the person's
+ * and a project can be written by anybody who edits it. A path is refused when
+ *
+ * - it is not already in canonical form (`isCleanPath`: relative, `/`-separated, no `..`, nothing
+ *   hidden, no `:`, at most 12 names of at most 100 plain ASCII characters);
+ * - a name could not be written safely on Windows: it ends with a dot or a space (Windows drops
+ *   both, so `a.` would be `a`) or is a device name (`con`, `nul`, `com1`, `lpt1`, ... with or
+ *   without an extension);
+ * - it resolves outside the folder (`insideFolder`), which the rule above already rules out and
+ *   which is checked again on the real, resolved path anyway;
+ * - in a set of paths, 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.
+ */
+/** Why a path is not safe: the cloud's rule, or a name Windows cannot keep. */
+export type PathProblem = "rule" | "windows-name" | "windows-dot";
+/** Why a path is not safe in a set of paths. */
+export type SetProblem = "letter-case" | "file-and-folder";
+/** Why one path cannot be written safely anywhere, or undefined when it can. */
+export declare function pathProblem(path: string): PathProblem | undefined;
+/**
+ * The paths of a set that cannot be written beside the others, each with why: the later of two
+ * paths that differ only in letter case, and a path that is also the folder of another one.
+ */
+export declare function setProblems(paths: Iterable<string>): Map<string, SetProblem>;
+/**
+ * A path the cloud answered, safe to print: control characters and line separators (an escape
+ * sequence in a name would reach the person's terminal) are written as `\uXXXX`. A path that
+ * passes the path rule has none.
+ */
+export declare function printablePath(path: string): string;
+/**
+ * The paths among `paths` that are the losers of a name collision: those the service lists as
+ * `shown` in `collisions`, and any `<path>~<id>` whose `<path>` is a valid path. The service shows
+ * such a path in its answers but never keeps one; it is never written and never sent.
+ */
+export declare function collisionLosers(paths: Iterable<string>, collisions: readonly unknown[]): Set<string>;
+/**
+ * Where a project path lands under a folder, as a native path, or undefined when the resolved
+ * result is not inside the folder (or is the folder itself). `folder` is absolute.
+ */
+export declare function insideFolder(folder: string, path: string): string | undefined;
+//# sourceMappingURL=cloud-paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-paths.d.ts","sourceRoot":"","sources":["../src/cloud-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,cAAc,GAAG,aAAa,CAAC;AAClE,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,iBAAiB,CAAC;AAK3D,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAOjE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAkB5E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD;AAKD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EACvB,UAAU,EAAE,SAAS,OAAO,EAAE,GAC7B,GAAG,CAAC,MAAM,CAAC,CAcb;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO7E"}

package/dist/cloud-paths.js

@@ -0,0 +1,104 @@
+/**
+ * What a path of a cloud project must be before it may be written under a folder (`cli-cloud`,
+ * "Pull"): one rule for `pull` and for every command that reads a cloud project into a folder's
+ * place (`review --base cloud`).
+ *
+ * The cloud already refuses every path that breaks its path rule, so what arrives is what the
+ * service kept; the command line does not take that on trust, because the folder is the person's
+ * and a project can be written by anybody who edits it. A path is refused when
+ *
+ * - it is not already in canonical form (`isCleanPath`: relative, `/`-separated, no `..`, nothing
+ *   hidden, no `:`, at most 12 names of at most 100 plain ASCII characters);
+ * - a name could not be written safely on Windows: it ends with a dot or a space (Windows drops
+ *   both, so `a.` would be `a`) or is a device name (`con`, `nul`, `com1`, `lpt1`, ... with or
+ *   without an extension);
+ * - it resolves outside the folder (`insideFolder`), which the rule above already rules out and
+ *   which is checked again on the real, resolved path anyway;
+ * - in a set of paths, 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.
+ */
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { isCleanPath } from "@meltemi/diagrams-project";
+/** The device names Windows reserves, with or without an extension. */
+const DEVICE_NAME = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i;
+/** Why one path cannot be written safely anywhere, or undefined when it can. */
+export function pathProblem(path) {
+    if (!isCleanPath(path))
+        return "rule";
+    for (const name of path.split("/")) {
+        if (/[. ]$/.test(name))
+            return "windows-dot";
+        if (DEVICE_NAME.test(name))
+            return "windows-name";
+    }
+    return undefined;
+}
+/**
+ * The paths of a set that cannot be written beside the others, each with why: the later of two
+ * paths that differ only in letter case, and a path that is also the folder of another one.
+ */
+export function setProblems(paths) {
+    const sorted = [...new Set(paths)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const problems = new Map();
+    const seen = new Set();
+    const folders = new Set();
+    for (const path of sorted) {
+        const lower = path.toLowerCase();
+        if (seen.has(lower))
+            problems.set(path, "letter-case");
+        seen.add(lower);
+        const names = lower.split("/");
+        for (let end = 1; end < names.length; end++)
+            folders.add(names.slice(0, end).join("/"));
+    }
+    for (const path of sorted) {
+        if (!problems.has(path) && folders.has(path.toLowerCase())) {
+            problems.set(path, "file-and-folder");
+        }
+    }
+    return problems;
+}
+/**
+ * A path the cloud answered, safe to print: control characters and line separators (an escape
+ * sequence in a name would reach the person's terminal) are written as `\uXXXX`. A path that
+ * passes the path rule has none.
+ */
+export function printablePath(path) {
+    return path.replace(/[\p{Cc}\p{Zl}\p{Zp}]/gu, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+/** A path the service made for the loser of a name collision: `<path>~<id>`, 16 base32 characters. */
+const LOSER = /^(.+)~[a-z2-7]{16}$/;
+/**
+ * The paths among `paths` that are the losers of a name collision: those the service lists as
+ * `shown` in `collisions`, and any `<path>~<id>` whose `<path>` is a valid path. The service shows
+ * such a path in its answers but never keeps one; it is never written and never sent.
+ */
+export function collisionLosers(paths, collisions) {
+    const losers = new Set();
+    for (const collision of collisions) {
+        const shown = typeof collision === "object" && collision !== null
+            ? collision.shown
+            : undefined;
+        if (typeof shown === "string")
+            losers.add(shown);
+    }
+    for (const path of paths) {
+        const stem = LOSER.exec(path)?.[1];
+        if (stem !== undefined && isCleanPath(stem))
+            losers.add(path);
+    }
+    return losers;
+}
+/**
+ * Where a project path lands under a folder, as a native path, or undefined when the resolved
+ * result is not inside the folder (or is the folder itself). `folder` is absolute.
+ */
+export function insideFolder(folder, path) {
+    const target = resolve(folder, ...path.split("/"));
+    const from = relative(folder, target);
+    if (from === "" || from === ".." || from.startsWith(`..${sep}`) || isAbsolute(from)) {
+        return undefined;
+    }
+    return target;
+}
+//# sourceMappingURL=cloud-paths.js.map

package/dist/cloud-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-paths.js","sourceRoot":"","sources":["../src/cloud-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAOxD,uEAAuE;AACvE,MAAM,WAAW,GAAG,+CAA+C,CAAC;AAEpE,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,aAAa,CAAC;QAC7C,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,cAAc,CAAC;IACpD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QACvD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1F,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAC3D,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,OAAO,CACjB,wBAAwB,EACxB,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACnE,CAAC;AACJ,CAAC;AAED,sGAAsG;AACtG,MAAM,KAAK,GAAG,qBAAqB,CAAC;AAEpC;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAuB,EACvB,UAA8B;IAE9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,KAAK,GACT,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI;YACjD,CAAC,CAAE,SAAiC,CAAC,KAAK;YAC1C,CAAC,CAAC,SAAS,CAAC;QAChB,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,IAAI,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,IAAY;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACpF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/credentials.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Where the command line keeps its sign-in (`cli-cloud`, "Signing in from the command line"):
+ * `credentials.json` in the user's configuration folder, one entry `{ token, id, user }` per host,
+ * and how a command finds the host and the token it uses.
+ *
+ * - The host is `--host`, else `MELTEMI_HOST`, else `https://diagrams.meltemi.dev`: never a
+ *   manifest's (`checkManifestHost` fails with `cloud.host-mismatch` when `project.json` names
+ *   another one).
+ * - The token is `MELTEMI_TOKEN` in the environment, else the file's entry for the host.
+ * - The file is written owner-only (`0o600`, in a `0o700` folder) where the system has such modes,
+ *   through a temporary file and a rename, so a failure never leaves half a file. Windows keeps the
+ *   ACLs the user's profile folder has.
+ * - A file that cannot be read as credentials is reported (`credentials.corrupt`) and never
+ *   overwritten.
+ */
+/** The service every cloud command talks to unless `--host` or `MELTEMI_HOST` says otherwise. */
+export declare const DEFAULT_HOST = "https://diagrams.meltemi.dev";
+/** The folder of the configuration, and the file of the credentials in it. */
+export declare const CONFIGURATION_FOLDER = "meltemi-diagrams";
+export declare const CREDENTIALS_FILE = "credentials.json";
+type Env = Readonly<Record<string, string | undefined>>;
+export interface ConfigurationOptions {
+    /** The environment: `APPDATA`, `XDG_CONFIG_HOME`, `HOME`, `USERPROFILE`. */
+    readonly env: Env;
+    /** The platform, `process.platform` by default. */
+    readonly platform?: NodeJS.Platform;
+    /** The user's home folder, from the environment or the system by default. */
+    readonly home?: string;
+}
+/**
+ * The folder of the configuration: `%APPDATA%\meltemi-diagrams` on Windows;
+ * `$XDG_CONFIG_HOME/meltemi-diagrams` elsewhere (an absolute value only, as the specification
+ * says), else `~/.config/meltemi-diagrams`.
+ */
+export declare function configurationFolder(options: ConfigurationOptions): string;
+/** The credentials file of an environment. */
+export declare function credentialsPath(options: ConfigurationOptions): string;
+/**
+ * The host a cloud command talks to: `--host` (`flag`), else `MELTEMI_HOST`, else the default. An
+ * empty `MELTEMI_HOST` counts as not set, as CI expands an unset variable. The answer is the
+ * normalised origin. Throws `cloud.host-invalid` for a text that is not an origin and
+ * `cloud.insecure-host` for `http:` anywhere but the loopback (`127.0.0.1`, `localhost`, `[::1]`),
+ * before anything is sent.
+ */
+export declare function resolveHost(options: {
+    readonly flag?: string | undefined;
+    readonly env: Env;
+}): string;
+/**
+ * Fails with `cloud.host-mismatch`, naming both hosts and `--host`, when a project's `cloud.host`
+ * is not the host the command resolved. A manifest never chooses where a token goes. Call it before
+ * any request; `manifestHost` is `project.json`'s `cloud.host` (absent when it names none).
+ */
+export declare function checkManifestHost(resolved: string, manifestHost: string | null | undefined): void;
+export interface StoredUser {
+    readonly sub: string;
+    readonly name: string;
+}
+/** What is kept for one host: the token, its id at the service, and who it is for. */
+export interface StoredEntry {
+    readonly token: string;
+    readonly id: string;
+    readonly user: StoredUser;
+}
+/** The token a command uses, and where it came from. */
+export interface ResolvedToken {
+    readonly token: string;
+    /** `environment`: `MELTEMI_TOKEN`; `file`: the credentials file's entry for the host. */
+    readonly source: "environment" | "file";
+    /** The stored entry, when the token came from the file. */
+    readonly entry?: StoredEntry;
+}
+/** The token of `MELTEMI_TOKEN`, when it is set to something. */
+export declare function environmentToken(env: Env): string | undefined;
+/**
+ * The credentials file. A missing file is an empty one. A file that is not JSON, not an object, or
+ * whose `hosts` is not an object, or whose entry for the host asked about is not an entry, is
+ * `credentials.corrupt`; nothing is written over it, so the person can read what is there.
+ * Entries of other hosts and fields it does not know are kept as they were found.
+ */
+export declare class CredentialsStore {
+    readonly path: string;
+    readonly folder: string;
+    constructor(options: ConfigurationOptions);
+    private corrupt;
+    private load;
+    /** Reads the file and makes its folder, so that a command finds out before it asks for a token. */
+    prepare(): void;
+    /** The hosts that have an entry. */
+    hosts(): string[];
+    /** The entry of a host, or undefined; `credentials.corrupt` when what is there is not an entry. */
+    entry(host: string): StoredEntry | undefined;
+    /** Keeps the entry of a host, replacing the one it had. */
+    save(host: string, entry: StoredEntry): void;
+    /** Forgets the entry of a host; whether there was one. The file goes when nothing is left in it. */
+    remove(host: string): boolean;
+    private unwritable;
+    /** Writes owner-only through a temporary file in the same folder, then renames it into place. */
+    private write;
+    /**
+     * The token a command uses for a host: `MELTEMI_TOKEN` when it is set (the file is not even
+     * read), else the host's entry. Undefined when there is none.
+     */
+    resolveToken(host: string, env: Env): ResolvedToken | undefined;
+}
+export {};
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiBH,iGAAiG;AACjG,eAAO,MAAM,YAAY,iCAAiC,CAAC;AAE3D,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AACvD,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAKnD,KAAK,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAExD,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAiBzE;AAED,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAMrE;AAID;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB,GAAG,MAAM,CAiBT;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAQjG;AAID,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAgBD,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC;IACxC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAG7D;AAUD;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,oBAAoB;IAMzC,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,IAAI;IA8BZ,mGAAmG;IACnG,OAAO,IAAI,IAAI;IAaf,oCAAoC;IACpC,KAAK,IAAI,MAAM,EAAE;IAIjB,mGAAmG;IACnG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAY5C,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAK5C,oGAAoG;IACpG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAgB7B,OAAO,CAAC,UAAU;IAQlB,iGAAiG;IACjG,OAAO,CAAC,KAAK;IAwBb;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,aAAa,GAAG,SAAS;CAMhE"}