@50arms/platform-mcp 0.0.0-stage → 0.1.437

package/dist/mini-app-checkout.js

@@ -0,0 +1,215 @@
+/**
+ * DX-5294 - the checkout side of `mini_app_publish`: which mini app target the dashboard declared, and whether THIS checkout (the one
+ * the design folder lives in) lets that target's build command run.
+ *
+ * Nothing here reads a file for a SETTING. The targets arrive from the dashboard (`GET /api/repos/<repo name>`, `mini_app_targets`); this
+ * module only checks them against the filesystem and git, which are facts of a checkout, not a setting. It never reads `.danxbot/` or any
+ * `config.yml`.
+ */
+import { execFile } from "node:child_process";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** The two keys of the one canonical target shape (no version field, no repair of a row missing one). */
+export const MINI_APP_TARGET_KEYS = ["name", "command"];
+/**
+ * The targets out of `GET /api/repos/<repo name>`'s body. A body without the array, or a row missing a field or holding a mistyped one, is a
+ * fault in what the dashboard answered: it fails loud naming the index and field, and the row is never repaired.
+ */
+export function parseMiniAppTargets(body, repo) {
+    const targets = body?.mini_app_targets;
+    if (!Array.isArray(targets)) {
+        throw new Error(`mini_app_publish: GET /api/repos/${repo} answered without a mini_app_targets array (a dashboard older than this tool, or a repo it does not serve?)`);
+    }
+    return targets.map((row, i) => {
+        const where = `mini_app_targets[${i}] of repo "${repo}"`;
+        if (typeof row !== "object" || row === null || Array.isArray(row))
+            throw new Error(`mini_app_publish: ${where} is not an object`);
+        const fields = row;
+        const extra = Object.keys(fields).filter((key) => !MINI_APP_TARGET_KEYS.includes(key));
+        if (extra.length > 0)
+            throw new Error(`mini_app_publish: ${where} has unknown field(s) ${extra.map((k) => `"${k}"`).join(", ")}`);
+        if (typeof fields.name !== "string" || fields.name === "") {
+            throw new Error(`mini_app_publish: ${where} has no "name" (a non-empty string is required)`);
+        }
+        const command = fields.command;
+        if (!Array.isArray(command) || command.length < 2 || command.some((part) => typeof part !== "string" || part === "")) {
+            throw new Error(`mini_app_publish: ${where} has no "command" (an array of at least two non-empty strings is required: the program, then the committed script)`);
+        }
+        return { name: fields.name, command: command };
+    });
+}
+/** The declared target named `name`, or the refusal an agent can act on: no targets at all, or the declared names. */
+export function pickMiniAppTarget(targets, name, repo) {
+    if (targets.length === 0) {
+        throw new Error(`mini_app_publish: repo ${repo} declares no mini app targets; add one in Settings > Board > General (Mini app targets)`);
+    }
+    const found = targets.find((t) => t.name === name);
+    if (found === undefined) {
+        throw new Error(`mini_app_publish: repo ${repo} declares no mini app target "${name}"; declared: ${targets.map((t) => `"${t.name}"`).join(", ")}`);
+    }
+    return found;
+}
+/** True when `child` is strictly inside `parent` (both absolute, already real paths). */
+export function isStrictlyInside(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+/** `p` relative to `base`, always with forward slashes (the form the dashboard stores repo-relative paths in). */
+export function relativePosix(base, p) {
+    return path.relative(base, p).split(path.sep).join("/");
+}
+/** Run `git -C <repoDir> <args>` (no shell); a non-zero exit is data (`ls-files --error-unmatch`, `diff --quiet` and `check-ignore -q` answer through it). */
+async function git(repoDir, args) {
+    try {
+        const { stdout, stderr } = await execFileAsync("git", ["-C", repoDir, ...args], { windowsHide: true });
+        return { code: 0, stdout, stderr };
+    }
+    catch (err) {
+        const failure = err;
+        if (typeof failure.code === "number")
+            return { code: failure.code, stdout: failure.stdout ?? "", stderr: failure.stderr ?? "" };
+        throw err;
+    }
+}
+/** git's trimmed stdout; any non-zero exit throws with git's own message. */
+async function gitText(repoDir, args) {
+    const run = await git(repoDir, args);
+    if (run.code !== 0)
+        throw new Error(`git ${args.join(" ")} failed (exit ${run.code}): ${run.stderr.trim()}`);
+    return run.stdout.trim();
+}
+/**
+ * The checkout the design directory lives in: `git -C <dir> rev-parse --show-toplevel` (no shell), a fact of the checkout and not a
+ * setting. It resolves a subdirectory, and a `.claude/worktrees/<n>` checkout, to that checkout's own top level.
+ */
+export async function resolveRepoRoot(dir) {
+    let top;
+    try {
+        top = await gitText(dir, ["rev-parse", "--show-toplevel"]);
+    }
+    catch (err) {
+        throw new Error(`mini_app_publish: dir "${dir}" is not inside a git checkout: ${err.message}`);
+    }
+    return realpath(top);
+}
+/** `git -C <repoRoot> rev-parse HEAD`: the commit the source files are taken from. */
+export async function readHeadCommit(repoRoot) {
+    return gitText(repoRoot, ["rev-parse", "HEAD"]);
+}
+/** The absolute, real path of `dir` (resolved against `cwd` when relative); it must exist and be a directory. */
+export async function resolveDesignDir(dir, cwd) {
+    const abs = path.resolve(cwd, dir);
+    let real;
+    try {
+        real = await realpath(abs);
+    }
+    catch {
+        throw new Error(`mini_app_publish: dir "${dir}" does not exist (resolved to ${abs})`);
+    }
+    if (!(await stat(real)).isDirectory())
+        throw new Error(`mini_app_publish: dir "${dir}" is not a directory`);
+    return real;
+}
+/**
+ * DX-5294: restated from `isUnsafeRepoRelativePath` in src/issues/repo-path-safety.ts (this package cannot import the backend): an
+ * absolute path, a Windows drive-letter path or a `..` segment.
+ */
+function isUnsafeRepoRelativePath(value) {
+    if (value.startsWith("/") || value.startsWith("\\"))
+        return true;
+    if (/^[A-Za-z]:[\\/]/.test(value))
+        return true; // Windows drive-letter absolute
+    return value.split(/[\\/]/).includes("..");
+}
+/**
+ * DX-5294: a repo-relative path a target may name (the build script): as the server's `isUnsafePath` in
+ * src/issues/mini-app-targets.ts, which also refuses any backslash. The parity test in src/dispatch/design-publish-restated-constants.test.ts pins the two.
+ */
+export const isUnsafeTargetPath = (value) => value.includes("\\") || isUnsafeRepoRelativePath(value);
+/** DX-5294: the program must be a bare name (no path separator, no whitespace), as the server's rule; pinned by the same parity test. */
+export const isInvalidProgram = (program) => /[\\/\s]/.test(program);
+/** The Windows programs that are `.cmd` shims: a spawn with no shell cannot start one. */
+const WINDOWS_SHIM_PROGRAMS = new Set(["npm", "npx", "yarn", "pnpm"]);
+/** The design folder must hold no file tracked by git and must be ignored by it (design folders are gitignored working files). */
+async function requireUntrackedAndIgnored(repoRoot, rel) {
+    const tracked = await git(repoRoot, ["ls-files", "--", rel]);
+    if (tracked.code !== 0)
+        throw new Error(`mini_app_publish: git ls-files failed (exit ${tracked.code}) for dir "${rel}": ${tracked.stderr.trim()}`);
+    if (tracked.stdout.trim() !== "") {
+        throw new Error(`mini_app_publish: dir "${rel}" holds files tracked by git; a design folder is a gitignored working folder: untrack it or use another folder`);
+    }
+    const ignored = await git(repoRoot, ["check-ignore", "-q", "--", rel]);
+    if (ignored.code === 1) {
+        throw new Error(`mini_app_publish: dir "${rel}" is not ignored by git; a design folder is a gitignored working folder: add it to .gitignore`);
+    }
+    if (ignored.code !== 0)
+        throw new Error(`mini_app_publish: git check-ignore failed (exit ${ignored.code}) for dir "${rel}": ${ignored.stderr.trim()}`);
+}
+/**
+ * Check a target against the checkout BEFORE anything is built or posted. Every refusal names the target and the field:
+ *  1. `command[0]` is a bare program name and `command[1]` a safe repo-relative path;
+ *  2. on Windows the program is not a `.cmd`/`.bat` shim (a spawn without a shell cannot start one);
+ *  3. the design folder is inside the repo root, not tracked by git, and ignored by it (design folders are gitignored working files);
+ *  4. `command[1]`, the build script, is tracked and unchanged from HEAD.
+ */
+export async function checkTarget(target, repo, repoRoot, dirAbs, platform) {
+    const refuse = (field, value, why) => new Error(`mini_app_publish: target "${target.name}" of repo ${repo}: ${field} "${value}" ${why} (checkout ${repoRoot})`);
+    const [program, script] = target.command;
+    if (isInvalidProgram(program))
+        throw refuse("command[0]", program, "must be a bare program name, with no path separator or whitespace");
+    const lower = program.toLowerCase();
+    if (platform === "win32" && (WINDOWS_SHIM_PROGRAMS.has(lower) || /\.(cmd|bat)$/.test(lower))) {
+        throw refuse("command[0]", program, "is a .cmd shim, which cannot be started without a shell: name `node` and a committed script instead, e.g. [\"node\", \"scripts/build-mini-app.mjs\"]");
+    }
+    if (isUnsafeTargetPath(script))
+        throw refuse("command[1]", script, "must be a repo-relative path with no `..` segment, backslash, absolute path or drive letter");
+    const designDirRel = relativePosix(repoRoot, dirAbs);
+    if (!isStrictlyInside(repoRoot, dirAbs))
+        throw new Error(`mini_app_publish: dir "${dirAbs}" is not inside the repo root ${repoRoot}`);
+    await requireUntrackedAndIgnored(repoRoot, designDirRel);
+    // DX-5294 known limit: this proves the NAMED script is committed and unchanged, not what that script imports.
+    const known = await git(repoRoot, ["ls-files", "--error-unmatch", "--", script]);
+    if (known.code === 1)
+        throw refuse("command[1]", script, "is not tracked by git: commit the build script before publishing");
+    if (known.code !== 0)
+        throw new Error(`mini_app_publish: git ls-files failed (exit ${known.code}) for ${script}: ${known.stderr.trim()}`);
+    const changed = await git(repoRoot, ["diff", "--quiet", "HEAD", "--", script]);
+    if (changed.code === 1)
+        throw refuse("command[1]", script, "has changes against HEAD: commit the build script before publishing");
+    if (changed.code !== 0)
+        throw new Error(`mini_app_publish: git diff failed (exit ${changed.code}) for ${script}: ${changed.stderr.trim()}`);
+    return { repoRoot, dirAbs, designDirRel };
+}
+/**
+ * Every file under `dir` as `{path, content}`: the path repo-relative with forward slashes, the content strict UTF-8 (a file that is
+ * not refuses, naming it; a byte-order mark is kept, never stripped). The server's file-count and size caps answer a 413 for a
+ * directory that is too large; this reads what is there and does not guess at them.
+ */
+export async function readSourceFiles(dirAbs, repoRoot) {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    const files = [];
+    const walk = async (current) => {
+        for (const entry of (await readdir(current, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                const bytes = await readFile(full);
+                try {
+                    files.push({ path: relativePosix(repoRoot, full), content: decoder.decode(bytes) });
+                }
+                catch {
+                    throw new Error(`mini_app_publish: ${relativePosix(repoRoot, full)} is not valid UTF-8 text; a design folder holds text files only`);
+                }
+            }
+            else {
+                throw new Error(`mini_app_publish: ${relativePosix(repoRoot, full)} is not a plain file or directory; a design folder holds plain files only`);
+            }
+        }
+    };
+    await walk(dirAbs);
+    return files;
+}

package/dist/mini-app-output.js

@@ -0,0 +1,111 @@
+/**
+ * DX-5294 / DX-6477 - what a mini app target's build wrote, folded into ONE self-contained HTML document. ONE module for it: `mini_app_publish` (`mini-app-build.ts`)
+ * and the designer's local viewer command (`.danxbot/mini-apps/check-design.mjs`) both build the page here, so the page a designer checks is the page the publish sends,
+ * with the same `</script` and `<!--` escapes and the same refusals.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { relativePosix } from "./mini-app-checkout.js";
+export const INDEX_HTML = "index.html";
+/**
+ * Two sequences in a script's text break the HTML parse of an inline script, and each has a spelling the JS parser reads as the same text inside a
+ * string, regex or template: `</script` would end the element early (`<\/script`), and `<!--` (a bundled HTML highlighter's comment regex) puts the HTML
+ * parser in its "escaped" state, where a later `<script` (the same highlighter's tag regex) makes the real `</script>` stop ending the element, so the
+ * page's own closing tags become JS text ("Unexpected token '<'", DX-5781). `<!--` becomes backslash, `x3C`, `!--`: the less-than as a hex escape, which
+ * a string, a regex (with or without the `u` flag) and a template all read as the same character.
+ */
+const ESCAPED_COMMENT_OPEN = "\\x3C!--";
+function escapeScript(js) {
+    return js.replace(/<\/(script)/gi, "<\\/$1").replace(/<!--/g, ESCAPED_COMMENT_OPEN);
+}
+function refEndsWith(ref, name) {
+    const clean = ref.split(/[?#]/)[0];
+    return clean === name || clean.endsWith(`/${name}`);
+}
+/**
+ * Fold the built page's one script and one stylesheet into the HTML: the `<script ... src>` that references the JS file becomes an
+ * inline module script (with `</script` escaped), and the `<link rel="stylesheet" href>` that references the CSS file becomes a
+ * `<style>`. A tag the build did not write for that file is a failure of this fold and throws; the document is never checked for
+ * relative references here (the dashboard's parse5 check owns that).
+ */
+export function inlineAssets(html, js, css) {
+    let out = html;
+    let scripts = 0;
+    out = out.replace(/<script\b[^>]*\bsrc=(["'])([^"']*)\1[^>]*>\s*<\/script>/gi, (tag, _quote, src) => {
+        if (!refEndsWith(src, js.name))
+            return tag;
+        scripts += 1;
+        return `<script type="module">\n${escapeScript(js.text)}\n</script>`;
+    });
+    if (scripts !== 1)
+        throw new Error(`mini_app_publish: the built index.html has ${scripts} <script> tags for ${js.name}; expected exactly 1`);
+    if (/<\/style/i.test(css.text)) {
+        throw new Error(`mini_app_publish: ${css.name} contains "</style" and cannot be inlined into a <style> element`);
+    }
+    let links = 0;
+    out = out.replace(/<link\b[^>]*>/gi, (tag) => {
+        if (!/\brel=(["'])stylesheet\1/i.test(tag))
+            return tag;
+        const href = /\bhref=(["'])([^"']*)\1/i.exec(tag)?.[2];
+        if (href === undefined || !refEndsWith(href, css.name))
+            return tag;
+        links += 1;
+        return `<style>\n${css.text}\n</style>`;
+    });
+    if (links !== 1)
+        throw new Error(`mini_app_publish: the built index.html has ${links} stylesheet links for ${css.name}; expected exactly 1`);
+    return out;
+}
+async function listFiles(dir) {
+    const found = [];
+    const walk = async (current) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else if (entry.isFile())
+                found.push(full);
+            // DX-5294: a link (or any other entry) is named, never silently skipped: the output must be plain files the build wrote
+            else
+                throw new Error(`mini_app_publish: the build wrote ${relativePosix(dir, full)}, which is not a plain file: the output must be only ${INDEX_HTML}, one .js and one .css`);
+        }
+    };
+    await walk(dir);
+    return found.sort();
+}
+/**
+ * Read what the build wrote. The output directory must hold exactly `index.html` (a build tool may keep its path below the root, so it may sit in
+ * a subdirectory), ONE `.js` and ONE `.css`: anything else, such as a second chunk or an emitted asset, fails naming the file.
+ */
+export async function readBuildOutput(outDir) {
+    const files = await listFiles(outDir);
+    const slots = { html: [], js: [], css: [] };
+    const extras = [];
+    for (const file of files) {
+        const ext = path.extname(file).toLowerCase();
+        if (path.basename(file) === INDEX_HTML)
+            slots.html.push(file);
+        else if (ext === ".js")
+            slots.js.push(file);
+        else if (ext === ".css")
+            slots.css.push(file);
+        else
+            extras.push(file);
+    }
+    extras.push(...slots.html.slice(1), ...slots.js.slice(1), ...slots.css.slice(1));
+    if (extras.length > 0) {
+        const named = extras.map((f) => relativePosix(outDir, f)).sort();
+        throw new Error(`mini_app_publish: the build wrote an unexpected file ${named.join(", ")}: the output must be only ${INDEX_HTML}, one .js and one .css`);
+    }
+    for (const [kind, label] of [["html", INDEX_HTML], ["js", ".js file"], ["css", ".css file"]]) {
+        if (slots[kind].length === 0)
+            throw new Error(`mini_app_publish: the build wrote no ${label}`);
+    }
+    const asset = async (file) => ({ name: path.basename(file), text: await readFile(file, "utf8") });
+    return { html: await asset(slots.html[0]), js: await asset(slots.js[0]), css: await asset(slots.css[0]) };
+}
+/** The build output folder as the one page the dashboard receives: read it (exactly `index.html`, one `.js`, one `.css`) and fold the script and stylesheet in. */
+export async function foldBuildOutput(outDir) {
+    const built = await readBuildOutput(outDir);
+    return inlineAssets(built.html.text, built.js, built.css);
+}

package/dist/mini-app-publish.js

@@ -0,0 +1,154 @@
+/**
+ * DX-5294 - the `mini_app_publish` flow: build a page with the repo's OWN mini app (a build command a target names, run in the agent's
+ * checkout) and publish it as a revision of one of an existing card's designs, or as the first revision of a new design on it
+ * (DX-4077, DX-5193). It replaces `design_publish`.
+ *
+ * It lives in this package, not behind `50arms_api`, because it is agent-specific: the build runs where the source is (the agent's
+ * own checkout or worktree) and the dashboard holds no connected repo's source. Every dashboard call goes through the same client
+ * `50arms_api` uses, so it carries the session's credential, trace and session headers.
+ *
+ * The design goes on an EXISTING card (`destination.card_id`, any card but an Epic or Feature, DX-5164): this tool never creates a card.
+ * `destination.design_no` adds a revision to that existing design (`POST .../designs/<no>/revisions`); `destination.design_title` starts a
+ * new design (`POST .../designs`, the title fixed for good). Exactly one of the two, refused before any call.
+ *
+ * `target.repo` names the repo whose mini app builds the page; omitted, it is the repo of the card's board (the danxbot repo's own mini
+ * app is reached by naming it).
+ *
+ * ORDER, so a failure leaves as little behind as it can: the arguments, then the card's board, then the repo and its targets (the
+ * dashboard answers; a refusal comes back verbatim), then the checkout checks, then the build, then the screenshot, and only THEN the
+ * revision is posted. A failed check, build or screenshot never leaves anything on the card; a refused revision comes back verbatim with
+ * the `card_id` and the built page's path.
+ */
+import { buildMiniApp, writeLocalHtml } from "./mini-app-build.js";
+import { checkTarget, parseMiniAppTargets, pickMiniAppTarget, readHeadCommit, readSourceFiles, resolveDesignDir, resolveRepoRoot, } from "./mini-app-checkout.js";
+import { captureScreenshot } from "./design-screenshot.js";
+import { danxbotApi } from "./handlers.js";
+function fail(message) {
+    throw new Error(`mini_app_publish: ${message}`);
+}
+function field(body, name, where) {
+    const value = body?.[name];
+    if (typeof value !== "string" || value === "")
+        fail(`${where} answered without "${name}"`);
+    return value;
+}
+/** DX-5512: a board ref on the wire is a positive integer; anything else is a dashboard fault, never repaired. */
+function refField(body, name, where) {
+    const value = body?.[name];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+        fail(`${where} answered without "${name}" as a positive integer`);
+    return value;
+}
+/** The board the card lives on, read from the card: a revision goes on the card's own board. */
+async function readCardBoard(client, cardId) {
+    const card = await danxbotApi(client, {
+        method: "GET",
+        path: `/api/issues/${encodeURIComponent(cardId)}`,
+        query: { fields: { board_id: true } },
+    });
+    if (!card.ok)
+        return card;
+    return { ok: true, board: refField(card.body, "board_id", `GET /api/issues/${cardId}`) };
+}
+export async function miniAppPublish(client, args, deps) {
+    // DX-4729: refused before any call, so a blank note never leaves a built page or a screenshot behind.
+    if (args.note.trim() === "")
+        fail("`note` is required: say what changed since the last revision, which decision note it answers and what is still open");
+    const { card_id: cardId } = args.destination;
+    // DX-5193: exactly one of design_no / design_title, refused before any call so a bad pair never builds a page.
+    const hasNo = args.destination.design_no !== undefined;
+    const hasTitle = args.destination.design_title !== undefined;
+    if (hasNo === hasTitle) {
+        fail("pass exactly one of `destination.design_no` (add a revision to that design of the card) or `destination.design_title` (start a new design on the card)");
+    }
+    if (args.destination.design_title?.trim() === "")
+        fail("`destination.design_title` must not be blank");
+    // DX-5856: a new design names the element it decides (its design problem is that element's); a revision stays on its design's problem.
+    if (hasTitle && args.destination.design_element === undefined)
+        fail("`destination.design_element` is required with `destination.design_title`: name the one thing this design decides (e.g. \"Indicator pill\")");
+    if (hasNo && args.destination.design_element !== undefined)
+        fail("`destination.design_element` goes only with `destination.design_title`: a revision stays on its design's problem");
+    if (args.destination.design_element?.trim() === "")
+        fail("`destination.design_element` must not be blank");
+    const boardOrRefusal = await readCardBoard(client, cardId);
+    if (!boardOrRefusal.ok)
+        return boardOrRefusal;
+    const { board } = boardOrRefusal;
+    // DX-5294: an explicit `target.repo` (a repo's name) names the repo (danxbot's own mini app); otherwise the dashboard owns board -> repo: the repo is
+    // read from the board, never parsed out of its id and never from an env var.
+    let repo = args.target.repo;
+    if (repo === undefined) {
+        const boardRow = await danxbotApi(client, { method: "GET", path: `/api/boards/${board}` });
+        if (!boardRow.ok)
+            return boardRow;
+        repo = field(boardRow.body, "repo_name", `GET /api/boards/${board}`);
+    }
+    // The targets are a dashboard setting, never a file in the repo.
+    const repoRow = await danxbotApi(client, {
+        method: "GET",
+        path: `/api/repos/${repo}`,
+        query: { fields: { mini_app_targets: true } },
+    });
+    if (!repoRow.ok)
+        return repoRow;
+    const target = pickMiniAppTarget(parseMiniAppTargets(repoRow.body, repo), args.target.name, repo);
+    const dirAbs = await resolveDesignDir(args.dir, deps.cwd);
+    const repoRoot = await resolveRepoRoot(dirAbs);
+    const checked = await checkTarget(target, repo, repoRoot, dirAbs, deps.platform ?? process.platform);
+    const sourceFiles = await readSourceFiles(checked.dirAbs, repoRoot);
+    const builtFromCommit = await readHeadCommit(repoRoot);
+    const { html, buildId } = await buildMiniApp({ command: target.command, repoRoot, designDirRel: checked.designDirRel }, deps.buildTimeoutMs, deps.buildPipeGraceMs);
+    const localHtmlPath = await writeLocalHtml(buildId, html);
+    const shot = await captureScreenshot(html, { rootAbs: repoRoot, cwd: deps.cwd }, args.option_groups ?? []);
+    const designRoute = hasTitle
+        ? `/api/issues/${encodeURIComponent(cardId)}/designs`
+        : `/api/issues/${encodeURIComponent(cardId)}/designs/${args.destination.design_no}/revisions`;
+    let published;
+    try {
+        published = await danxbotApi(client, {
+            method: "POST",
+            path: designRoute,
+            body: {
+                ...(hasTitle ? { title: args.destination.design_title, element: args.destination.design_element } : {}),
+                note: args.note,
+                target: target.name,
+                design_dir: checked.designDirRel,
+                source_files: sourceFiles,
+                bundle_html: html,
+                built_from_commit: builtFromCommit,
+                ...(shot.png_base64 === null ? {} : { screenshot_png_base64: shot.png_base64 }),
+                ...(args.option_groups === undefined ? {} : { option_groups: args.option_groups }),
+                checklist: args.checklist,
+                browser_check: args.browser_check,
+                ...(args.problem_statement === undefined ? {} : { problem_statement: args.problem_statement }),
+                ...(args.problem_summary === undefined ? {} : { problem_summary: args.problem_summary }),
+                ...(args.problem_context === undefined ? {} : { problem_context: args.problem_context }),
+            },
+            board,
+        });
+    }
+    catch (err) {
+        // A network or server fault: the page is built and still matters to the retry.
+        throw new Error(`${err.message} (no revision was published to ${cardId}; the page is at ${localHtmlPath})`);
+    }
+    if (!published.ok)
+        return { ...published, card_id: cardId, local_html_path: localHtmlPath };
+    const answer = published.body;
+    if (typeof answer?.design_no !== "number")
+        fail(`POST ${designRoute} answered without a design_no`);
+    if (typeof answer.revision_no !== "number")
+        fail(`POST ${designRoute} answered without a revision_no`);
+    const body = {
+        card_id: cardId,
+        design_no: answer.design_no,
+        revision_no: answer.revision_no,
+        dashboard_url: `${deps.baseUrl.replace(/\/+$/, "")}/board/${cardId}`,
+        local_html_path: localHtmlPath,
+        screenshot: shot.screenshot,
+        browser_check: args.browser_check,
+        ...(args.browser_check.status === "not_checked"
+            ? { warning: `Published WITHOUT a browser check (${args.browser_check.note}). The revision carries a big red warning on its design problem and in the full-screen design dialog, and the operator is told. Check it in a browser and publish a new revision that says "checked".` }
+            : {}),
+    };
+    return { ok: true, status: published.status, body };
+}

package/dist/mini-app-restore.js

@@ -0,0 +1,175 @@
+/**
+ * DX-6070 - the `mini_app_restore` flow: put one revision of a design back on disk. A design's source (its gitignored folder of text files)
+ * is stored with EVERY revision on the dashboard, but a designer in another worktree, or on another machine, has no folder to revise. This
+ * reads one revision's stored source (`GET /api/issues/<card>/designs/<no>/revisions/<rev>/source`) and writes each file at its repo-relative
+ * path under the agent's repo root (resolved as `mini_app_publish` resolves it, `resolveRepoRoot`).
+ *
+ * It lives here, not behind `50arms_api`, because it writes local files.
+ *
+ * ALL-OR-NOTHING: every path is checked, and every existing file compared, BEFORE the first write. A path that leaves the revision's
+ * `design_dir` (absolute, `..`, a backslash, outside the folder) refuses the whole restore; so does an existing file with different content
+ * (that is unpublished work, never overwritten), naming each such file. A file with equal content is `unchanged`; a file in the folder the
+ * revision lacks is left alone and named in `extra_local`.
+ */
+import { lstat, mkdir, readFile, readdir, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { isStrictlyInside, relativePosix, resolveRepoRoot } from "./mini-app-checkout.js";
+import { danxbotApi } from "./handlers.js";
+function fail(message) {
+    throw new Error(`mini_app_restore: ${message}`);
+}
+/** A repo-relative POSIX path that is safe to join under a root: non-empty, not absolute (either flavour), no backslash, no drive letter, no `.`/`..`/empty segment. */
+function isSafeRelative(p) {
+    if (p === "" || p.includes("\\") || p.includes("\0") || p.startsWith("/") || /^[A-Za-z]:/.test(p))
+        return false;
+    return p.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+function parseSource(body, where) {
+    const b = body;
+    if (typeof b?.design_dir !== "string" || typeof b.built_from_commit !== "string" || !Array.isArray(b.source_files)) {
+        fail(`${where} answered without design_dir, built_from_commit and source_files`);
+    }
+    const files = b.source_files.map((f, i) => {
+        const file = f;
+        if (typeof file?.path !== "string" || typeof file.content !== "string")
+            fail(`${where} answered source_files[${i}] without a string path and content`);
+        return { path: file.path, content: file.content };
+    });
+    return { design_dir: b.design_dir, built_from_commit: b.built_from_commit, source_files: files };
+}
+/** The design's latest revision number, from the card's `designs` relation. */
+async function latestRevisionNo(client, cardId, designNo) {
+    const card = await danxbotApi(client, { method: "GET", path: `/api/issues/${encodeURIComponent(cardId)}`, query: { fields: { designs: true } } });
+    if (!card.ok)
+        return card;
+    const designs = card.body?.designs;
+    if (!Array.isArray(designs))
+        fail(`GET /api/issues/${cardId} answered without a designs array`);
+    const rows = designs;
+    const design = rows.find((d) => d.design_no === designNo);
+    if (design === undefined)
+        fail(`card ${cardId} has no design ${designNo}; its designs: ${rows.map((d) => String(d.design_no)).join(", ") || "none"}`);
+    if (typeof design.latest_revision_no !== "number")
+        fail(`card ${cardId} design ${designNo} answered without a latest_revision_no`);
+    return { ok: true, revisionNo: design.latest_revision_no };
+}
+/** Every file under `dir` (absolute), repo-relative POSIX; nothing when `dir` does not exist. */
+async function listFolder(dir, repoRoot) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await listFolder(full, repoRoot)));
+        else
+            out.push(relativePosix(repoRoot, full));
+    }
+    return out;
+}
+/** What is at `abs`: nothing, a plain file (its text), or something else (a directory, a link) that is in the way. */
+async function existingAt(abs) {
+    let info;
+    try {
+        info = await lstat(abs);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { kind: "missing" };
+        throw err;
+    }
+    if (!info.isFile())
+        return { kind: "other" };
+    return { kind: "file", content: (await readFile(abs)).toString("utf8") };
+}
+/** The nearest existing ancestor of `abs`, resolved through symlinks: a restore never writes through a link that leaves the repo. */
+async function realAncestor(abs) {
+    let current = abs;
+    for (;;) {
+        try {
+            return await realpath(current);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw err;
+            const parent = path.dirname(current);
+            if (parent === current)
+                throw err;
+            current = parent;
+        }
+    }
+}
+export async function miniAppRestore(client, args, deps) {
+    let revisionNo = args.revision_no;
+    if (revisionNo === undefined) {
+        const latest = await latestRevisionNo(client, args.card_id, args.design_no);
+        if (!latest.ok)
+            return latest;
+        revisionNo = latest.revisionNo;
+    }
+    const route = `/api/issues/${encodeURIComponent(args.card_id)}/designs/${args.design_no}/revisions/${revisionNo}/source`;
+    const answer = await danxbotApi(client, { method: "GET", path: route });
+    if (!answer.ok)
+        return answer;
+    const source = parseSource(answer.body, `GET ${route}`);
+    if (!isSafeRelative(source.design_dir))
+        fail(`the revision's design_dir "${source.design_dir}" is not a safe repo-relative path; nothing was written`);
+    const designPrefix = `${source.design_dir}/`;
+    const outside = source.source_files.filter((f) => !isSafeRelative(f.path) || !f.path.startsWith(designPrefix));
+    if (outside.length > 0) {
+        fail(`${outside.length} path(s) sit outside the design folder "${source.design_dir}" (absolute, "..", a backslash or another folder); nothing was written: ${outside.map((f) => JSON.stringify(f.path)).join(", ")}`);
+    }
+    const repoRoot = await resolveRepoRoot(deps.cwd);
+    const targets = source.source_files.map((f) => ({ ...f, abs: path.join(repoRoot, ...f.path.split("/")) }));
+    const leaving = [];
+    const differing = [];
+    const unchanged = [];
+    const toWrite = [];
+    for (const t of targets) {
+        const ancestor = await realAncestor(t.abs);
+        if (ancestor !== repoRoot && !isStrictlyInside(repoRoot, ancestor)) {
+            leaving.push(t.path);
+            continue;
+        }
+        const existing = await existingAt(t.abs);
+        if (existing.kind === "missing")
+            toWrite.push(t);
+        else if (existing.kind === "file" && existing.content === t.content)
+            unchanged.push(t.path);
+        else
+            differing.push(t.path);
+    }
+    if (leaving.length > 0)
+        fail(`${leaving.length} path(s) resolve outside the repo checkout through a link; nothing was written: ${leaving.join(", ")}`);
+    if (differing.length > 0) {
+        fail(`${differing.length} existing local file(s) differ from revision ${revisionNo} (unpublished work is never overwritten); nothing was written: ${differing.join(", ")}. ` +
+            "Publish or move them first, or restore into a checkout that lacks the folder.");
+    }
+    for (const t of toWrite) {
+        await mkdir(path.dirname(t.abs), { recursive: true });
+        await writeFile(t.abs, t.content, "utf8");
+    }
+    const restored = new Set(source.source_files.map((f) => f.path));
+    const extraLocal = (await listFolder(path.join(repoRoot, ...source.design_dir.split("/")), repoRoot)).filter((p) => !restored.has(p)).sort();
+    return {
+        ok: true,
+        status: answer.status,
+        body: {
+            design_dir: source.design_dir,
+            revision_no: revisionNo,
+            built_from_commit: source.built_from_commit,
+            written: toWrite.map((t) => t.path),
+            unchanged,
+            extra_local: extraLocal,
+        },
+    };
+}