@meltemi/diagrams-cli 0.0.0-stage → 1.9.0

package/dist/publish-command.js

@@ -0,0 +1,311 @@
+/**
+ * `publish` (`cli-cloud`, "Publish"): the catalog of the folder's project as a web page of the cloud
+ * service.
+ *
+ * The order, and why:
+ *
+ * 1. The project and the session: the folder's manifest names the cloud project (`cloud.project`,
+ *    or `--project`), the host is `--host`, `MELTEMI_HOST` or the default, and `cloud.host-mismatch`
+ *    and "not signed in" fail before any request.
+ * 2. `--unpublish` ends here: one `DELETE`, nothing is built or pushed.
+ * 3. `GET …/publish` first: it is the owner's, so a project the person may not publish (`access.denied`,
+ *    `project.not-found`) fails before the catalog is built, and it says whether a handle is chosen.
+ * 4. The catalog is built in memory, exactly as `build catalog` builds it (same generator, same
+ *    defaults, the `--lang` language), before anything is sent: a catalog with nothing in it, with
+ *    errors under `--strict`, or too large for a page, fails with nothing pushed and nothing
+ *    published.
+ * 5. The handle: the first publication needs one (`--handle`, or asked on a terminal). With
+ *    `--handle` the handle is set first (`PATCH /api/account`); the service lets a token do that; a
+ *    service that answers `403 request.forbidden` instead makes it `publish.handle-in-page`.
+ * 6. The folder is pushed when it differs from the cloud project: the command of `push`, with its
+ *    comparison and its question (`--force` answers it, as in CI), so what is published is what the
+ *    cloud holds.
+ * 7. `PUT …/publish`, and the public address printed on a line of its own.
+ */
+import { statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { catalogScript } from "@meltemi/diagrams-catalog/node";
+import { ProjectSessions, buildCatalog } from "@meltemi/diagrams-editor/node";
+import { sortDiagnostics } from "@meltemi/diagrams-language";
+import { BRAND_NAME } from "@meltemi/diagrams-layout";
+import { CLOUD_LIMITS, toProjectPath } from "@meltemi/diagrams-project";
+import { formatSize } from "./build-command.js";
+import { openCloud, usage, usageError, } from "./cloud-context.js";
+import { CloudError, EXIT_OK, EXIT_USAGE, isCloudError } from "./cloud-errors.js";
+import { messages } from "./messages/index.js";
+import { withDetails } from "./project-errors.js";
+import { pushCommand } from "./push-command.js";
+/** The handle and the page name, as the service accepts them. */
+const HANDLE = /^[a-z0-9-]{3,30}$/;
+const SLUG = /^[a-z0-9-]{1,60}$/;
+/** The most a publish request may weigh as JSON: the service's own cap. */
+const REQUEST_BYTES = 24 * 1024 * 1024;
+/**
+ * The size that makes a page too large for the service, or undefined when it fits: the HTML over
+ * 16 MiB of UTF-8, or the request that carries it over 24 MiB (JSON escapes quotes and the like, so
+ * a page below the first limit can still be above the second). Checked here so that nothing is sent.
+ */
+export function oversize(slug, html) {
+    const htmlBytes = Buffer.byteLength(html);
+    if (htmlBytes > CLOUD_LIMITS.publishBytes)
+        return htmlBytes;
+    // A request cannot be smaller than its page: only a large page needs the exact count.
+    if (htmlBytes <= REQUEST_BYTES / 6)
+        return undefined;
+    const requestBytes = Buffer.byteLength(JSON.stringify({ slug, html }));
+    return requestBytes > REQUEST_BYTES ? requestBytes : undefined;
+}
+/** How many times a handle typed on a terminal may be wrong before the command gives up. */
+const HANDLE_ATTEMPTS = 3;
+/** A page name made of a project's name: lower-case ASCII letters and digits with single hyphens. */
+export function slugOf(text) {
+    const slug = text
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+/, "")
+        .slice(0, 60)
+        .replace(/-+$/, "");
+    return slug === "" ? "diagrams" : slug;
+}
+function parse(context, args, help) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...args],
+            options: {
+                slug: { type: "string" },
+                handle: { type: "string" },
+                unpublish: { type: "boolean", default: false },
+                project: { type: "string" },
+                host: { type: "string" },
+                force: { type: "boolean", default: false },
+                strict: { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+            },
+            allowPositionals: true,
+            strict: true,
+        });
+    }
+    catch (error) {
+        return usageError(context, error, help);
+    }
+    const values = parsed.values;
+    if (values.help) {
+        context.stdout(help);
+        return EXIT_OK;
+    }
+    const t = messages();
+    if (parsed.positionals.length > 1)
+        return usage(context, t.common.oneProject, help);
+    if (values.slug !== undefined && !SLUG.test(values.slug)) {
+        return usage(context, t.cloud.publish.slugInvalid(values.slug), help);
+    }
+    if (values.handle !== undefined && !HANDLE.test(values.handle)) {
+        return usage(context, t.cloud.publish.handleOption(values.handle), help);
+    }
+    if (values.unpublish) {
+        for (const [name, given] of [
+            ["--handle", values.handle !== undefined],
+            ["--force", values.force],
+            ["--strict", values.strict],
+        ]) {
+            if (given)
+                return usage(context, t.common.cannotCombine("--unpublish", name), help);
+        }
+    }
+    return {
+        folder: parsed.positionals[0] ?? ".",
+        slug: values.slug,
+        handle: values.handle,
+        unpublish: values.unpublish === true,
+        project: values.project,
+        host: values.host,
+        force: values.force === true,
+        strict: values.strict === true,
+    };
+}
+// ----------------------------------------------------------------------------------- the build
+/** Prints diagnostics as `validate` and `build catalog` print them. */
+function printDiagnostics(context, path, diagnostics) {
+    for (const d of diagnostics) {
+        context.stdout(`${path}:${d.range.start.line}:${d.range.start.column}: ${d.severity} ${d.code} ${d.message}\n`);
+        for (const hint of d.hints ?? []) {
+            context.stdout(`    ${messages().common.hint}: ${hint}\n`);
+        }
+    }
+}
+/** The diagnostics of `project.json`, the plugins and the assets, by file: what `build catalog` shows first. */
+function projectDiagnostics(workspace) {
+    const manifest = workspace.manifest();
+    const byPath = new Map();
+    if (manifest.diagnostics.length > 0)
+        byPath.set(manifest.path, [...manifest.diagnostics]);
+    for (const [path, list] of [
+        ...workspace.limits(),
+        ...workspace.plugins().diagnostics,
+        ...workspace.assets().diagnostics,
+    ]) {
+        byPath.set(path, [...(byPath.get(path) ?? []), ...list]);
+    }
+    return new Map([...byPath].map(([path, list]) => [path, sortDiagnostics(list)]));
+}
+/** The catalog of a folder's project, exactly as `build catalog` builds it, and whether it has errors. */
+function buildPublication(context, projects, workspace) {
+    let errors = false;
+    for (const [path, diagnostics] of projectDiagnostics(workspace)) {
+        printDiagnostics(context, context.display(path), diagnostics);
+        errors ||= diagnostics.some((d) => d.severity === "error");
+    }
+    const build = buildCatalog(workspace, projects, {
+        generator: `${BRAND_NAME} ${context.toolVersion}`,
+        script: catalogScript,
+    });
+    for (const [file, diagnostics] of [...build.diagnostics].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+        printDiagnostics(context, context.display(file), diagnostics);
+        errors ||= diagnostics.some((d) => d.severity === "error");
+    }
+    const t = messages().build;
+    for (const entry of build.skipped) {
+        context.stderr(`${context.name} ${context.command}: ${t.skipped(`${context.display(entry.path)}#${entry.id}`, entry.reason)}\n`);
+    }
+    for (const warning of build.warnings) {
+        context.stderr(`${context.name} ${context.command}: ${t.warning(warning)}\n`);
+    }
+    return { build, errors };
+}
+// ---------------------------------------------------------------------------------- the handle
+/**
+ * The handle to set before publishing, or undefined when the account's own will do: the one given
+ * with `--handle` when it is not the account's already, else (the account has none) the one asked
+ * for on a terminal; without a terminal, `handle.required`.
+ */
+async function handleToSet(context, current, given) {
+    if (given !== undefined)
+        return given === current ? undefined : given;
+    if (current !== null)
+        return undefined;
+    const required = () => new CloudError("handle.required", "Choose a handle before the first publication.");
+    const t = messages().cloud;
+    if (context.ask === undefined)
+        throw required();
+    for (let attempt = 0; attempt < HANDLE_ATTEMPTS; attempt++) {
+        const answer = (await context.ask(t.publish.askHandle)).trim();
+        if (answer === "")
+            throw required();
+        if (HANDLE.test(answer))
+            return answer;
+        context.stderr(`${context.name} ${context.command}: ${t.errors.handleInvalid(answer)}\n`);
+    }
+    throw required();
+}
+// ---------------------------------------------------------------------------------- the command
+/**
+ * The `publish` command, with the step that pushes the folder given: `push`'s own command, which
+ * compares the folder with the cloud project and asks (or is forced), and answers its exit code.
+ */
+export function createPublishCommand(push) {
+    return async (args, context) => {
+        const help = messages().help.publish;
+        const options = parse(context, args, help);
+        if (typeof options === "number")
+            return options;
+        const t = messages().cloud;
+        const folder = toProjectPath(resolve(context.cwd, options.folder));
+        try {
+            if (!statSync(folder).isDirectory())
+                throw new Error("not a folder");
+        }
+        catch {
+            context.stderr(`${context.name} ${context.command}: ${messages().common.pathNotFound(options.folder)}\n`);
+            return EXIT_USAGE;
+        }
+        const projects = new ProjectSessions({
+            toolVersion: context.toolVersion,
+            ...(context.locale ? { locale: context.locale } : {}),
+        });
+        const workspace = projects.forFolder(folder);
+        const manifest = workspace.manifest().manifest;
+        const project = options.project ?? manifest?.cloud?.project;
+        if (project === undefined) {
+            throw new CloudError("cloud.no-project", "The folder names no cloud project.");
+        }
+        const { host, client } = openCloud(context, {
+            host: options.host,
+            manifestHost: manifest?.cloud?.host,
+        });
+        context.used.project = project;
+        const slug = options.slug ?? slugOf(manifest?.name ?? basename(workspace.root));
+        if (options.unpublish) {
+            try {
+                await client.unpublish(project, slug);
+            }
+            catch (error) {
+                throw isCloudError(error, "not-found")
+                    ? new CloudError("publish.not-published", error.message, { details: { slug } })
+                    : error;
+            }
+            context.stdout(`${t.publish.unpublished(slug)}\n`);
+            return EXIT_OK;
+        }
+        // The owner's route first: nothing is built for a project the person may not publish.
+        const state = await client.publication(project);
+        const { build, errors } = buildPublication(context, projects, workspace);
+        if (build.data.entries.length === 0) {
+            throw new CloudError("publish.empty", "The project has nothing to publish.");
+        }
+        if (options.strict && (errors || build.skipped.length > 0)) {
+            throw new CloudError("publish.errors", "The project has errors.");
+        }
+        const htmlBytes = Buffer.byteLength(build.html);
+        const tooLarge = oversize(slug, build.html);
+        if (tooLarge !== undefined) {
+            throw new CloudError("publish.too-large", "The catalog is larger than a page may be.", {
+                details: { bytes: tooLarge },
+            });
+        }
+        const handle = await handleToSet(context, state.handle, options.handle);
+        if (handle !== undefined) {
+            try {
+                await client.setHandle(handle);
+            }
+            catch (error) {
+                throw withDetails(isCloudError(error, "request.forbidden")
+                    ? new CloudError("publish.handle-in-page", error.message, { status: error.status })
+                    : error, { handle, current: state.handle });
+            }
+            context.stdout(`${t.publish.handleSet(handle)}\n`);
+        }
+        const pushed = await push([
+            options.folder,
+            "--project",
+            project,
+            "--host",
+            host,
+            ...(options.force ? ["--force"] : []),
+            ...(options.strict ? ["--strict"] : []),
+        ], context);
+        if (pushed !== EXIT_OK)
+            return pushed;
+        let published;
+        try {
+            published = await client.publish(project, { slug, html: build.html });
+        }
+        catch (error) {
+            throw withDetails(error, { slug, bytes: htmlBytes });
+        }
+        const diagrams = build.data.entries.filter((e) => e.kind === "diagram").length;
+        const b = messages().build;
+        context.stdout(`${t.publish.published([
+            b.diagrams(diagrams),
+            b.stories(build.data.entries.length - diagrams),
+            ...(build.data.entities.length > 0 ? [b.entities(build.data.entities.length)] : []),
+        ], formatSize(htmlBytes))}\n${published.url}\n`);
+        return EXIT_OK;
+    };
+}
+/** `publish`, pushing the folder with `push`'s own command. */
+export const publishCommand = createPublishCommand(pushCommand);
+//# sourceMappingURL=publish-command.js.map

package/dist/publish-command.js.map

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

package/dist/pull-command.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `mdg pull [<id>] [folder] [--version <n>] [--force]` (`cli-cloud`, "Pull"): writes a cloud
+ * project's files into a folder, and never writes anything it has not checked first.
+ *
+ * Every path the cloud answers is checked before the first byte is written (`cloud-paths.ts`): it
+ * must be in the canonical form the cloud keeps (`isCleanPath`, so no `..`, no absolute path, no
+ * backslash, nothing hidden such as `.git/hooks/post-checkout`), a name Windows could keep, not
+ * differ from another path only in letter case, and resolve inside the folder; and it must not go
+ * through a link in the folder (a link is never followed out of it). One that fails refuses the
+ * whole pull with `pull.unsafe-path` naming it, and nothing is written, not even the folder.
+ *
+ * Then, per file: absent in the folder, it is written (images and fonts are fetched by hash and
+ * checked against it); identical, it is left alone; existing and different, it is listed and kept
+ * unless `--force`; a folder where a file belongs is kept too. Files only in the folder stay. The
+ * losers of a name collision (`<path>~<id>`) are skipped with a note. `project.json` gains
+ * `cloud` when it has none, through `setJsonObjectField`, and nothing else of it changes. The exit
+ * code is 1 when a file was kept.
+ */
+import { type CloudCommand } from "./cloud-context.js";
+export declare const pullCommand: CloudCommand;
+//# sourceMappingURL=pull-command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pull-command.d.ts","sourceRoot":"","sources":["../src/pull-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAyBH,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AA6F5B,eAAO,MAAM,WAAW,EAAE,YA+GzB,CAAC"}

package/dist/pull-command.js

@@ -0,0 +1,300 @@
+/**
+ * `mdg pull [<id>] [folder] [--version <n>] [--force]` (`cli-cloud`, "Pull"): writes a cloud
+ * project's files into a folder, and never writes anything it has not checked first.
+ *
+ * Every path the cloud answers is checked before the first byte is written (`cloud-paths.ts`): it
+ * must be in the canonical form the cloud keeps (`isCleanPath`, so no `..`, no absolute path, no
+ * backslash, nothing hidden such as `.git/hooks/post-checkout`), a name Windows could keep, not
+ * differ from another path only in letter case, and resolve inside the folder; and it must not go
+ * through a link in the folder (a link is never followed out of it). One that fails refuses the
+ * whole pull with `pull.unsafe-path` naming it, and nothing is written, not even the folder.
+ *
+ * Then, per file: absent in the folder, it is written (images and fonts are fetched by hash and
+ * checked against it); identical, it is left alone; existing and different, it is listed and kept
+ * unless `--force`; a folder where a file belongs is kept too. Files only in the folder stay. The
+ * losers of a name collision (`<path>~<id>`) are skipped with a note. `project.json` gains
+ * `cloud` when it has none, through `setJsonObjectField`, and nothing else of it changes. The exit
+ * code is 1 when a file was kept.
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { CLOUD_LIMITS, CLOUD_PROJECT_ID, MANIFEST_NAME, readManifest, toProjectPath, } from "@meltemi/diagrams-project";
+import { createNodeHost } from "@meltemi/diagrams-project/node";
+import { sha256Hex } from "./cloud-client.js";
+import { openCloud, usage, usageError, } from "./cloud-context.js";
+import { CloudError, EXIT_FAILED, EXIT_OK } from "./cloud-errors.js";
+import { withCloudField } from "./cloud-manifest.js";
+import { collisionLosers, insideFolder, pathProblem, printablePath, setProblems, } from "./cloud-paths.js";
+import { messages } from "./messages/index.js";
+import { withDetails } from "./project-errors.js";
+/** Looks at the folder's tree for a path, one name at a time, never following a link. */
+function inspect(root, path) {
+    const names = path.split("/");
+    let current = root;
+    for (let i = 0; i < names.length; i++) {
+        current = join(current, names[i]);
+        let stats;
+        try {
+            stats = lstatSync(current);
+        }
+        catch (error) {
+            const code = error.code;
+            return code === "ENOENT" || code === "ENOTDIR" ? { state: "free" } : { state: "blocked" };
+        }
+        if (stats.isSymbolicLink())
+            return { state: "link" };
+        if (i < names.length - 1) {
+            if (!stats.isDirectory())
+                return { state: "blocked" };
+        }
+        else if (stats.isFile()) {
+            return { state: "file", file: current, size: stats.size };
+        }
+        else {
+            return { state: "blocked" };
+        }
+    }
+    return { state: "free" };
+}
+/** Writes a file through a temporary file in its folder and a rename, so a link there is replaced, not followed. */
+function writeFile(target, data) {
+    mkdirSync(dirname(target), { recursive: true });
+    const temporary = `${target}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temporary, data, { flag: "wx" });
+        renameSync(temporary, target);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+/** Whether the file in the folder holds what the cloud holds. */
+function sameContent(slot, kind, content) {
+    try {
+        if (kind === "binary") {
+            if (slot.size > CLOUD_LIMITS.binaryBytes)
+                return false;
+            return sha256Hex(readFileSync(slot.file)) === content;
+        }
+        // A text is content, byte for byte: the line endings and a byte order mark included.
+        return (slot.size === Buffer.byteLength(content) &&
+            readFileSync(slot.file).equals(Buffer.from(content, "utf8")));
+    }
+    catch {
+        // A file that cannot be read cannot be said to match: it is kept, or fails to be written.
+        return false;
+    }
+}
+export const pullCommand = async (args, context) => {
+    const help = messages().help.pull;
+    const t = messages().cloud.pull;
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...args],
+            options: {
+                host: { type: "string" },
+                version: { type: "string" },
+                force: { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+            },
+            allowPositionals: true,
+            strict: true,
+        });
+    }
+    catch (error) {
+        return usageError(context, error, help);
+    }
+    const values = parsed.values;
+    if (values.help) {
+        context.stdout(help);
+        return EXIT_OK;
+    }
+    if (parsed.positionals.length > 2)
+        return usage(context, t.tooMany, help);
+    let version;
+    if (values.version !== undefined) {
+        if (!/^[0-9]+$/.test(values.version) || Number(values.version) < 1) {
+            return usage(context, t.version(values.version), help);
+        }
+        version = Number(values.version);
+    }
+    // One argument is the id when it has the shape of one, else the folder.
+    let id;
+    let given;
+    if (parsed.positionals.length === 2)
+        [id, given] = parsed.positionals;
+    else if (parsed.positionals[0] !== undefined) {
+        if (CLOUD_PROJECT_ID.test(parsed.positionals[0]))
+            id = parsed.positionals[0];
+        else
+            given = parsed.positionals[0];
+    }
+    const folder = resolve(context.cwd, given ?? ".");
+    if (existsSync(folder) && !statSync(folder).isDirectory()) {
+        throw new CloudError("pull.not-a-folder", `${folder} exists and is not a folder.`, {
+            details: { path: context.display(folder) },
+        });
+    }
+    const manifest = readManifest(createNodeHost(), toProjectPath(folder), {
+        toolVersion: context.toolVersion,
+    }).manifest;
+    const linked = manifest?.cloud ?? null;
+    const { host, client } = openCloud(context, { host: values.host, manifestHost: linked?.host });
+    const project = id ?? linked?.project;
+    if (project === undefined) {
+        throw new CloudError("pull.no-project", "No cloud project is named.");
+    }
+    context.used.project = project;
+    if (id !== undefined && linked !== null && linked.project !== id) {
+        throw new CloudError("pull.other-project", "The folder is another cloud project's.", {
+            details: { project: id, linked: linked.project },
+        });
+    }
+    const answer = await read(client, project, version);
+    const everything = [...Object.keys(answer.files), ...Object.keys(answer.binaries)];
+    const losers = collisionLosers(everything, answer.collisions);
+    const entries = plan(folder, answer, everything.filter((path) => !losers.has(path)), values.force);
+    // Everything is checked; from here on the folder is written.
+    const lines = [];
+    let written = 0;
+    let identical = 0;
+    const kept = [];
+    for (const entry of entries) {
+        if (entry.action === "same") {
+            identical++;
+        }
+        else if (entry.action === "write") {
+            try {
+                const data = entry.kind === "text" ? entry.content : await client.blob(project, entry.content);
+                writeFile(entry.target, data);
+            }
+            catch (error) {
+                if (error instanceof CloudError)
+                    throw withDetails(error, { project });
+                throw new CloudError("pull.write", error.message, {
+                    details: { path: entry.path, reason: error.message },
+                });
+            }
+            written++;
+            lines.push(t.wrote(entry.path));
+        }
+        else {
+            kept.push(entry.action === "blocked" ? t.inTheWay(entry.path) : t.kept(entry.path));
+        }
+    }
+    for (const path of [...losers].filter((p) => everything.includes(p)).sort()) {
+        lines.push(t.loser(printablePath(path)));
+    }
+    for (const line of lines)
+        context.stdout(`${line}\n`);
+    for (const line of kept)
+        context.stdout(`${line}\n`);
+    if (kept.length > 0 && !values.force)
+        context.stdout(`${t.keptHint}\n`);
+    const failure = recordProject(context, folder, host, project);
+    context.stdout(`${t.pulled(project, version ?? null, context.display(folder), written, identical, kept.length)}\n`);
+    if (failure !== undefined)
+        throw failure;
+    return kept.length > 0 ? EXIT_FAILED : EXIT_OK;
+};
+/** The project's files, or a version's, as the service answers them. */
+async function read(client, project, version) {
+    try {
+        if (version === undefined)
+            return await client.files(project);
+        return {
+            ...(await client.readVersion(project, version)),
+            collisions: [],
+        };
+    }
+    catch (error) {
+        throw withDetails(error, { project, ...(version === undefined ? {} : { version }) });
+    }
+}
+/**
+ * What to do with each of the cloud's paths in a folder, after every one has been checked. Throws
+ * `pull.unsafe-path` (nothing written) for the first path that is not safe.
+ */
+function plan(folder, answer, paths, force) {
+    const root = existsSync(folder) ? realpathSync(folder) : folder;
+    const unsafe = [];
+    const sorted = [...paths].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const named = sorted.filter((path) => pathProblem(path) === undefined);
+    const together = setProblems(named);
+    const entries = [];
+    for (const path of sorted) {
+        const target = pathProblem(path) === undefined ? insideFolder(root, path) : undefined;
+        if (target === undefined || together.has(path)) {
+            unsafe.push(path);
+            continue;
+        }
+        const text = Object.hasOwn(answer.files, path);
+        const kind = text ? "text" : "binary";
+        const content = text ? answer.files[path] : answer.binaries[path];
+        const slot = inspect(root, path);
+        if (slot.state === "link")
+            unsafe.push(path);
+        else if (slot.state === "blocked")
+            entries.push({ path, target, kind, content, action: "blocked" });
+        else if (slot.state === "free")
+            entries.push({ path, target, kind, content, action: "write" });
+        else if (sameContent(slot, kind, content)) {
+            entries.push({ path, target, kind, content, action: "same" });
+        }
+        else
+            entries.push({ path, target, kind, content, action: force ? "write" : "keep" });
+    }
+    if (unsafe.length > 0) {
+        // The path is the cloud's to name and the terminal is the person's: it is printed escaped.
+        const shown = printablePath(unsafe[0]);
+        throw new CloudError("pull.unsafe-path", `The cloud project holds ${shown}, which is not a safe path inside the folder.`, { details: { path: shown } });
+    }
+    return entries;
+}
+/**
+ * Adds `cloud` to the folder's `project.json` when it has none (or one that is not valid), through
+ * `setJsonObjectField`: the rest of the file is untouched, byte for byte. Answers the failure, when
+ * there is one, so that the summary is printed first.
+ */
+function recordProject(context, folder, host, project) {
+    const t = messages().cloud.pull;
+    const file = join(folder, MANIFEST_NAME);
+    if (!existsSync(file)) {
+        context.stdout(`${t.noManifest}\n`);
+        return undefined;
+    }
+    const current = readManifest(createNodeHost(), toProjectPath(folder), {
+        toolVersion: context.toolVersion,
+    }).manifest;
+    // A project.json pulled from the cloud may name ANOTHER project: a copy of a project (the page's
+    // Duplicate) keeps its files verbatim. The folder belongs to the project it was pulled from, so
+    // the setting is rewritten, or the next push would overwrite the project it names.
+    if (current?.cloud && current.cloud.project === project && current.cloud.host === host) {
+        return undefined;
+    }
+    // A link is never followed (the files of a pull are not written through one either): the setting
+    // is not written into whatever a link points at.
+    if (lstatSync(file).isSymbolicLink()) {
+        return new CloudError("pull.manifest-not-updated", "project.json is a link.", {
+            details: { reason: "project.json is a link, and a pull never writes through one" },
+        });
+    }
+    try {
+        const text = readFileSync(file, "utf8");
+        const edited = withCloudField(text, host, project);
+        if (edited !== text)
+            writeFileSync(file, edited, "utf8");
+        context.stdout(`${t.recorded(context.display(file))}\n`);
+        return undefined;
+    }
+    catch (error) {
+        return new CloudError("pull.manifest-not-updated", error.message, {
+            details: { reason: error.message },
+        });
+    }
+}
+//# sourceMappingURL=pull-command.js.map