@thehammer/danx-dashboard-mcp 0.1.278 → 0.1.280

package/README.md

@@ -50,6 +50,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `danxbot_api_list` | No args. Lists the routes this caller's credential may reach as `{routes: ["METHOD /path"]}` (one bare string per route, exactly what `danxbot_api_spec` takes; a dispatch's own callbacks are in it) — call this first when you don't know the route for what you need to do. |
 | `danxbot_api_spec` | `{endpoints}` (comma-joined `METHOD /path` list, required, min 1). Returns the exact OpenAPI contract for those routes — call this when you know the route but not its exact request/response shape. |
 | `attach_file` | `{card_id, path, replaces?, primary?, filename?, content_type?}` — the server reads the LOCAL file at `path` (absolute, `/tmp/a.png` or `C:\x\a.png`) and uploads it, so its bytes never pass through the agent's context. `replaces: <attachment id>` swaps that attachment's file in place (`PUT /api/issues/:id/attachments/:aid`: same id, name and cover flag) instead of adding one; `primary: true` makes it the card's single cover, atomically with the write. Reply: `{issue: <compact row>, attachment_id, url, thumbnail_url, is_primary}`. Shown to a key holding `cards.edit` (DX-4523); a dispatch profile still receives it only when its catalog selection names it (`slack-agent` and `work`, DX-4386, through `extraTools`). A screenshot of browser-visible work: first `primary: true`, then `replaces` at each milestone. |
+| `design_publish` | `{target, dir, card_id?, board?, title?, summary?, description?}` — builds a design with the TARGET repo's own Vite (resolved from the target's root at run time: this package depends on neither `vite` nor `playwright`) and publishes it as a revision of a Design card (DX-4077). `target` names one of the repo's design targets, read from the dashboard (`GET /api/repos/<repo>`, edited in Settings > Board > General), never from a file; `dir` holds `Design.tsx` under the target's root. The repo is the board's `repo_name` (`GET /api/boards/<board>`). The build runs in `<root>/.danx-design/<build-id>/` (removed afterwards), the page is written to `<tmpdir>/danx-design/<build-id>.html` before the upload, and a 1280x800 screenshot is taken when Playwright resolves from the target or this server's cwd (`screenshot: "none: <reason>"` otherwise, never a failed publish). Without `card_id` it creates the Design card first; a refused revision comes back verbatim with that `card_id`. Shown to a key holding `cards.edit`; opt-in, so a dispatch profile receives it only when its catalog selection names it (none does yet). |
 | `request_permission` | `{permissions, reason}` — asks a person to grant this key ONE MORE permission (see "Asking for one more permission" above). Answers at once with the approval URL and confirm code; the grant is picked up in the background. |
 
 There is no dedicated `resource_fields` tool (removed DX-3465 — it was a thin wrapper `danxbot_api` already reaches with no agent-specific behavior earning it its own tool). What an opt-in field TREE may name for one resource (`{resource, description, always, hashes, fields, relations}`) is `danxbot_api({method:"GET", path:"/api/resources/<resource>/fields"})` — install-global, no `board`; `resource: "issue"` is the root, and a relation's own `resource` in the response is what to call this again with, one level deeper.

package/dist/design-build.js

@@ -0,0 +1,259 @@
+/**
+ * DX-4077 - build a design with the TARGET repo's own Vite and fold the result into ONE self-contained HTML document.
+ *
+ * The package has no `vite` dependency and never will: Vite is resolved from the target's root at run time
+ * (`createRequire(<root>/package.json)`), so the design renders with exactly the repo's aliases, Tailwind, fonts and plugins. The
+ * build runs INSIDE `<root>/.danx-design/<build-id>/` (Vite refuses an HTML entry outside its root), and that directory is removed
+ * in a `finally`, whatever happened.
+ *
+ * This module carries no validator for the document it produces: that the document is self-contained is checked by exactly ONE
+ * validator, the dashboard's own parse5 check on the revision route, whose 400 comes back to the caller verbatim.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { isStrictlyInside, repoRelative } from "./design-checkout.js";
+/** The directory (inside the target root) every build gets its own subdirectory of; the target's `.gitignore` names it. */
+export const BUILD_ROOT_DIR = ".danx-design";
+export const INDEX_HTML = "index.html";
+export const ENTRY_FILE = "entry.tsx";
+export const CSS_FILE = "design.css";
+/** Inside the build dir: Vite's output, and its dependency cache (both removed with the dir). */
+const OUT_DIR = "out";
+const VITE_CACHE_DIR = ".vite";
+/** A build id unique per call, so two builds in one checkout never share a directory. */
+export function newBuildId() {
+    return `${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`;
+}
+/** A path as an import / `@import` / `@source` specifier from `fromDir`: relative, forward slashes, `./` when it stays at or below it. */
+function specifier(fromDir, target) {
+    const rel = repoRelative(fromDir, target);
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+/** A CSS string literal; a path that would need escaping is refused rather than guessed at. */
+function cssString(value) {
+    if (/["\\\r\n]/.test(value))
+        throw new Error(`design_publish: the path ${JSON.stringify(value)} cannot be written into a CSS string`);
+    return `"${value}"`;
+}
+/** The module specifier of a source file: its extension is dropped, so the target's bundler resolves it the way the app does. */
+function moduleSpecifier(fromDir, target) {
+    return specifier(fromDir, target).replace(/\.(tsx?|jsx?|mjs|cjs)$/, "");
+}
+/**
+ * The three files a build is generated from. `entry` imports the harness and the design and calls the harness's `mountDesign`.
+ * `design.css` imports the target's own stylesheet and names TWO Tailwind sources, the target's source AND the design directory:
+ * with the Vite root outside the app Tailwind skipped the app's own classes, and a design directory under a gitignored path is
+ * skipped by automatic detection (the DX-4077 experiment), so both are named.
+ */
+export function generateBuildFiles(input) {
+    const { buildDir } = input;
+    const indexHtml = `<!doctype html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n<meta name="viewport" content="width=device-width, initial-scale=1">\n` +
+        `<title>Design</title>\n</head>\n<body>\n<div id="root"></div>\n<script type="module" src="./${ENTRY_FILE}"></script>\n</body>\n</html>\n`;
+    const entry = `// Generated by design_publish; never edited by hand.\n` +
+        `import ${JSON.stringify(`./${CSS_FILE}`)};\n` +
+        `import { mountDesign } from ${JSON.stringify(moduleSpecifier(buildDir, input.harnessAbs))};\n` +
+        `import Design from ${JSON.stringify(moduleSpecifier(buildDir, path.join(input.dirAbs, "Design")))};\n\n` +
+        `const el = document.getElementById("root");\n` +
+        `if (el === null) throw new Error("design_publish entry: #root is missing");\n` +
+        `mountDesign(el, Design);\n`;
+    const css = `@import ${cssString(specifier(buildDir, input.stylesheetAbs))};\n` +
+        `@source ${cssString(specifier(buildDir, input.rootAbs))};\n` +
+        `@source ${cssString(specifier(buildDir, input.dirAbs))};\n`;
+    return { indexHtml, entry, css };
+}
+/** `</script` in a script's text would end the element early: `<\/script` is the same text to the JS parser inside a string, regex or template. */
+function escapeScript(js) {
+    return js.replace(/<\/(script)/gi, "<\\/$1");
+}
+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(`design_publish: the built index.html has ${scripts} <script> tags for ${js.name}; expected exactly 1`);
+    if (/<\/style/i.test(css.text)) {
+        throw new Error(`design_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(`design_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
+                found.push(full);
+        }
+    };
+    await walk(dir);
+    return found.sort();
+}
+/**
+ * Read what the build wrote. The output directory must hold exactly `index.html` (Vite keeps 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) => repoRelative(outDir, f)).sort();
+        throw new Error(`design_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(`design_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]) };
+}
+/** Vite as the TARGET repo resolves it from its own root; the package never depends on it. */
+export async function loadTargetVite(rootAbs) {
+    let resolved;
+    try {
+        resolved = createRequire(path.join(rootAbs, "package.json")).resolve("vite");
+    }
+    catch (err) {
+        throw new Error(`design_publish: "vite" does not resolve from the target root ${rootAbs} (install the repo's dependencies): ${err.message}`);
+    }
+    return (await import(/* @vite-ignore */ pathToFileURL(resolved).href));
+}
+function resolveInside(base, value) {
+    return typeof value === "string" && value !== "" ? path.resolve(base, value) : null;
+}
+/**
+ * The merged config's guard, run before anything is built. The frontend's own config sets `emptyOutDir: true` and `outDir: "dist"`, so
+ * a merge that failed to move them would empty the app's real `dist`: both the output directory and the cache directory must resolve
+ * inside the build dir, and the one entry must be exactly the generated page.
+ */
+export function assertConfigContained(merged, rootAbs, buildDir, indexHtml) {
+    const build = (merged.build ?? {});
+    const outDir = resolveInside(rootAbs, build.outDir);
+    const cacheDir = resolveInside(rootAbs, merged.cacheDir);
+    if (outDir === null || !isStrictlyInside(buildDir, outDir)) {
+        throw new Error(`design_publish: refusing to build: the merged build.outDir (${String(build.outDir)}) is not inside the build dir ${buildDir}`);
+    }
+    if (cacheDir === null || !isStrictlyInside(buildDir, cacheDir)) {
+        throw new Error(`design_publish: refusing to build: the merged cacheDir (${String(merged.cacheDir)}) is not inside the build dir ${buildDir}`);
+    }
+    const input = build.rollupOptions?.input;
+    if (typeof input !== "string" || path.resolve(rootAbs, input) !== indexHtml) {
+        throw new Error(`design_publish: refusing to build: the merged build.rollupOptions.input is not the generated ${indexHtml}`);
+    }
+}
+/**
+ * Build the design: generate the three files in a fresh `<root>/.danx-design/<build-id>/`, load the target's Vite and its config,
+ * merge the overrides, guard, build, read the output, fold it into one document. The build dir is removed in a `finally`; a failed
+ * cleanup never replaces the error that came first.
+ */
+export async function buildDesign(input) {
+    const buildDir = path.join(input.rootAbs, BUILD_ROOT_DIR, input.buildId);
+    let failed = false;
+    try {
+        await mkdir(buildDir, { recursive: true });
+        const indexHtml = path.join(buildDir, INDEX_HTML);
+        const files = generateBuildFiles({ buildDir, rootAbs: input.rootAbs, stylesheetAbs: input.stylesheetAbs, harnessAbs: input.harnessAbs, dirAbs: input.dirAbs });
+        await writeFile(indexHtml, files.indexHtml, "utf8");
+        await writeFile(path.join(buildDir, ENTRY_FILE), files.entry, "utf8");
+        await writeFile(path.join(buildDir, CSS_FILE), files.css, "utf8");
+        const vite = await loadTargetVite(input.rootAbs);
+        // "warn": Vite logs info to stdout, which on this stdio MCP server is the protocol channel; warnings and errors go to stderr.
+        const loaded = await vite.loadConfigFromFile({ command: "build", mode: "production" }, input.viteConfigAbs, input.rootAbs, "warn");
+        if (loaded === null)
+            throw new Error(`design_publish: Vite found no config at ${input.viteConfigAbs}`);
+        const outDir = path.join(buildDir, OUT_DIR);
+        const merged = vite.mergeConfig(loaded.config, {
+            // The repo's config is already loaded: the build must not read it a second time.
+            configFile: false,
+            root: input.rootAbs,
+            base: "./",
+            logLevel: "warn",
+            cacheDir: path.join(buildDir, VITE_CACHE_DIR),
+            build: {
+                outDir,
+                assetsInlineLimit: () => true,
+                cssCodeSplit: false,
+                modulePreload: false,
+                emptyOutDir: false,
+                reportCompressedSize: false,
+                rollupOptions: { input: indexHtml, output: { inlineDynamicImports: true } },
+            },
+        });
+        assertConfigContained(merged, input.rootAbs, buildDir, indexHtml);
+        await vite.build(merged);
+        const built = await readBuildOutput(outDir);
+        return { html: inlineAssets(built.html.text, built.js, built.css), buildId: input.buildId };
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        try {
+            await rm(buildDir, { recursive: true, force: true });
+            // The parent holds one directory per build in flight: removed when this was the last, left when another build still uses it.
+            // rmdir only succeeds on an EMPTY directory, so a concurrent build that has made its own subdirectory makes this fail (ENOTEMPTY) and
+            // the parent stays; a build that creates its dir between this rmdir and its own mkdir is safe because mkdir is recursive.
+            await rmdir(path.dirname(buildDir)).catch(() => undefined);
+        }
+        catch (cleanupError) {
+            // The error that ended the build is the one to report; a directory that could not be removed is named on stderr.
+            if (!failed)
+                throw cleanupError;
+            console.error(`[danx-dashboard-mcp] design_publish could not remove ${buildDir}: ${cleanupError.message}`);
+        }
+    }
+}
+/** `<os.tmpdir()>/danx-design/<build-id>.html`: the finished page, written before the upload so an agent can open it even when the revision is refused. */
+export async function writeLocalHtml(buildId, html) {
+    const dir = path.join(os.tmpdir(), "danx-design");
+    await mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${buildId}.html`);
+    await writeFile(file, html, "utf8");
+    return file;
+}

package/dist/design-checkout.js

@@ -0,0 +1,165 @@
+/**
+ * DX-4077 - the checkout side of `design_publish`: which design target the dashboard declared, and whether THIS checkout (the one
+ * the design directory lives in) holds what that target names.
+ *
+ * Nothing here reads a file for a SETTING. The targets arrive from the dashboard (`GET /api/repos/<repo>`, `design_targets`); this
+ * module only checks them against the filesystem, which is a fact of a checkout, not a setting: a path may be missing, or the
+ * directory may belong to another repo. 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 five keys of the one canonical target shape (DX-4077 / CP1: no version field, no repair of a row missing one). */
+export const TARGET_KEYS = ["name", "root", "vite_config", "stylesheet", "harness"];
+export const DESIGN_FILE = "Design.tsx";
+/**
+ * The targets out of `GET /api/repos/<repo>`'s body. A body without the array, or a row missing a key, is a fault in what the
+ * dashboard answered: it fails loud naming the index and key, and the row is never repaired.
+ */
+export function parseDesignTargets(body, repo) {
+    const targets = body?.design_targets;
+    if (!Array.isArray(targets)) {
+        throw new Error(`design_publish: GET /api/repos/${repo} answered without a design_targets array (a dashboard older than this tool, or a repo it does not serve?)`);
+    }
+    return targets.map((row, i) => {
+        if (typeof row !== "object" || row === null || Array.isArray(row)) {
+            throw new Error(`design_publish: design_targets[${i}] of repo "${repo}" is not an object`);
+        }
+        for (const key of TARGET_KEYS) {
+            const value = row[key];
+            if (typeof value !== "string" || value === "") {
+                throw new Error(`design_publish: design_targets[${i}] of repo "${repo}" has no "${key}" (a non-empty string is required)`);
+            }
+        }
+        return row;
+    });
+}
+/** The declared target named `name`, or the refusal an agent can act on: no targets at all, or the declared names. */
+export function pickDesignTarget(targets, name, repo) {
+    if (targets.length === 0) {
+        throw new Error(`design_publish: repo ${repo} declares no design targets; add one in Settings > Board > General (Design targets)`);
+    }
+    const found = targets.find((t) => t.name === name);
+    if (found === undefined) {
+        throw new Error(`design_publish: repo ${repo} declares no design 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 repoRelative(base, p) {
+    return path.relative(base, p).split(path.sep).join("/");
+}
+async function git(repoDir, args) {
+    const { stdout } = await execFileAsync("git", ["-C", repoDir, ...args], { windowsHide: true });
+    return 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 git(dir, ["rev-parse", "--show-toplevel"]);
+    }
+    catch (err) {
+        throw new Error(`design_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 git(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(`design_publish: dir "${dir}" does not exist (resolved to ${abs})`);
+    }
+    if (!(await stat(real)).isDirectory())
+        throw new Error(`design_publish: dir "${dir}" is not a directory`);
+    return real;
+}
+/**
+ * Check the target's declared paths against the checkout: each of `root` (a directory), `vite_config`, `stylesheet` and `harness`
+ * (files) resolves inside the repo root and exists, and the design directory is inside the root and holds `Design.tsx`. Every refusal
+ * names the field, the value and the repo, so a checkout that is not this repo fails here.
+ */
+export async function checkTarget(target, repo, repoRoot, dirAbs) {
+    const resolveField = async (field, kind) => {
+        const value = target[field];
+        const refuse = (why) => new Error(`design_publish: target "${target.name}" of repo ${repo}: ${field} "${value}" ${why} (checkout ${repoRoot})`);
+        const abs = path.resolve(repoRoot, value);
+        if (!isStrictlyInside(repoRoot, abs))
+            throw refuse("is outside the repo root");
+        let info;
+        try {
+            info = await stat(abs);
+        }
+        catch {
+            throw refuse("does not exist in this checkout");
+        }
+        if (kind === "directory" ? !info.isDirectory() : !info.isFile())
+            throw refuse(`is not a ${kind}`);
+        return realpath(abs);
+    };
+    const rootAbs = await resolveField("root", "directory");
+    const viteConfigAbs = await resolveField("vite_config", "file");
+    const stylesheetAbs = await resolveField("stylesheet", "file");
+    const harnessAbs = await resolveField("harness", "file");
+    if (!isStrictlyInside(rootAbs, dirAbs)) {
+        throw new Error(`design_publish: dir "${dirAbs}" is not inside the root "${target.root}" of target "${target.name}" (${rootAbs})`);
+    }
+    const designFile = path.join(dirAbs, DESIGN_FILE);
+    try {
+        if (!(await stat(designFile)).isFile())
+            throw new Error("not a file");
+    }
+    catch {
+        throw new Error(`design_publish: dir "${dirAbs}" holds no ${DESIGN_FILE}`);
+    }
+    return { repoRoot, rootAbs, viteConfigAbs, stylesheetAbs, harnessAbs, dirAbs };
+}
+/**
+ * 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: repoRelative(repoRoot, full), content: decoder.decode(bytes) });
+                }
+                catch {
+                    throw new Error(`design_publish: ${repoRelative(repoRoot, full)} is not valid UTF-8 text; a design directory holds text files only`);
+                }
+            }
+            else {
+                throw new Error(`design_publish: ${repoRelative(repoRoot, full)} is not a plain file or directory; a design directory holds plain files only`);
+            }
+        }
+    };
+    await walk(dirAbs);
+    return files;
+}

package/dist/design-publish.js

@@ -0,0 +1,133 @@
+/**
+ * DX-4077 - the `design_publish` flow: build a design against the repo's real components with the repo's own Vite, and publish it as
+ * a revision of a Design card.
+ *
+ * It lives in this package, not behind `danxbot_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 and no Vite. Every dashboard call goes through the same
+ * client `danxbot_api` uses, so it carries the session's credential, trace and session headers.
+ *
+ * ORDER, so a failure leaves as little behind as it can: the arguments, then the board and card, then the repo and its targets (the
+ * dashboard answers; a refusal comes back verbatim), then the checkout and the build, then the screenshot, and only THEN the card is
+ * created and the revision posted. A failed build or screenshot never leaves a card. The two writes are separate calls, so a refused
+ * revision leaves a Design card with no revision: that is not hidden or undone, the refusal comes back verbatim WITH the new
+ * `card_id`, and a retry with it adds revision 1 to the same card.
+ */
+import path from "node:path";
+import { buildDesign, newBuildId, writeLocalHtml } from "./design-build.js";
+import { checkTarget, DESIGN_FILE, parseDesignTargets, pickDesignTarget, readHeadCommit, readSourceFiles, repoRelative, resolveDesignDir, resolveRepoRoot, } from "./design-checkout.js";
+import { captureScreenshot } from "./design-screenshot.js";
+import { danxbotApi } from "./handlers.js";
+function fail(message) {
+    throw new Error(`design_publish: ${message}`);
+}
+function field(body, name, where) {
+    const value = body?.[name];
+    if (typeof value !== "string" || value === "")
+        fail(`${where} answered without "${name}"`);
+    return value;
+}
+/** The board the card lives on: the card's own (read from it), else the named one, else the server's, else a refusal naming `board`. */
+async function resolveBoard(client, args, deps) {
+    if (args.card_id === undefined) {
+        const board = args.board ?? deps.serverBoard;
+        if (board === undefined)
+            fail("no board: this server has none of its own, so name one in `board` (`<repo>:<slug>`)");
+        return { ok: true, board };
+    }
+    const card = await danxbotApi(client, {
+        method: "GET",
+        path: `/api/issues/${encodeURIComponent(args.card_id)}`,
+        query: { fields: { board_id: true } },
+    });
+    if (!card.ok)
+        return card;
+    const board = field(card.body, "board_id", `GET /api/issues/${args.card_id}`);
+    if (args.board !== undefined && args.board !== board) {
+        fail(`card ${args.card_id} lives on board ${board}, not ${args.board}: a revision goes on the card's own board, so omit \`board\` or name ${board}`);
+    }
+    return { ok: true, board };
+}
+export async function designPublish(client, args, deps) {
+    // With `card_id` the card already exists: its title, summary and description are not this call's to set, and silently ignoring them would hide the mistake.
+    if (args.card_id !== undefined) {
+        const given = ["title", "summary", "description"].filter((k) => args[k] !== undefined);
+        if (given.length > 0)
+            fail(`${given.map((k) => `\`${k}\``).join(", ")} name the card this call CREATES, so they cannot be combined with \`card_id\`: drop them to add a revision to ${args.card_id}`);
+    }
+    // No card to add to: it is created here, and a card needs a title and a summary. Refused before any call.
+    if (args.card_id === undefined && (args.title === undefined || args.summary === undefined)) {
+        fail("`title` and `summary` are required without `card_id` (they name the Design card this creates)");
+    }
+    const boardOrRefusal = await resolveBoard(client, args, deps);
+    if (!boardOrRefusal.ok)
+        return boardOrRefusal;
+    const { board } = boardOrRefusal;
+    // The dashboard owns board -> repo: the repo is read from the board, never parsed out of its id and never from an env var.
+    const boardRow = await danxbotApi(client, { method: "GET", path: `/api/boards/${encodeURIComponent(board)}` });
+    if (!boardRow.ok)
+        return boardRow;
+    const 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/${encodeURIComponent(repo)}`,
+        query: { fields: { design_targets: true } },
+    });
+    if (!repoRow.ok)
+        return repoRow;
+    const target = pickDesignTarget(parseDesignTargets(repoRow.body, repo), args.target, repo);
+    const dirAbs = await resolveDesignDir(args.dir, deps.cwd);
+    const repoRoot = await resolveRepoRoot(dirAbs);
+    const checked = await checkTarget(target, repo, repoRoot, dirAbs);
+    const sourceFiles = await readSourceFiles(checked.dirAbs, repoRoot);
+    const builtFromCommit = await readHeadCommit(repoRoot);
+    const { html, buildId } = await buildDesign({ ...checked, buildId: newBuildId() });
+    const localHtmlPath = await writeLocalHtml(buildId, html);
+    const shot = await captureScreenshot(html, { rootAbs: checked.rootAbs, cwd: deps.cwd });
+    let cardId = args.card_id;
+    if (cardId === undefined) {
+        const created = await danxbotApi(client, {
+            method: "POST",
+            path: "/api/issues",
+            // `description` is a creation-time seed: the route requires a string.
+            body: { type: "Design", plan: "mine", board, title: args.title, summary: args.summary, description: args.description ?? "" },
+            board,
+        });
+        if (!created.ok)
+            return { ...created, local_html_path: localHtmlPath };
+        cardId = field(created.body?.issue, "id", "POST /api/issues");
+    }
+    let published;
+    try {
+        published = await danxbotApi(client, {
+            method: "POST",
+            path: `/api/issues/${encodeURIComponent(cardId)}/design/revisions`,
+            body: {
+                target: target.name,
+                entry: repoRelative(repoRoot, path.join(checked.dirAbs, DESIGN_FILE)),
+                source_files: sourceFiles,
+                bundle_html: html,
+                built_from_commit: builtFromCommit,
+                ...(shot.png_base64 === null ? {} : { screenshot_png_base64: shot.png_base64 }),
+            },
+            board,
+        });
+    }
+    catch (err) {
+        // A network or server fault after the card exists: the card id and the page still matter to the retry.
+        throw new Error(`${err.message} (card ${cardId} exists with no revision from this call; retry with card_id "${cardId}"; the page is at ${localHtmlPath})`);
+    }
+    if (!published.ok)
+        return { ...published, card_id: cardId, local_html_path: localHtmlPath };
+    const revisionNo = published.body?.revision_no;
+    if (typeof revisionNo !== "number")
+        fail(`POST /api/issues/${cardId}/design/revisions answered without a revision_no`);
+    const body = {
+        card_id: cardId,
+        revision_no: revisionNo,
+        dashboard_url: `${deps.baseUrl.replace(/\/+$/, "")}/board/${cardId}`,
+        local_html_path: localHtmlPath,
+        screenshot: shot.screenshot,
+    };
+    return { ok: true, status: published.status, body };
+}

package/dist/design-screenshot.js

@@ -0,0 +1,98 @@
+/**
+ * DX-4077 (operator decision, DX-4083 problem 1856) - the screenshot a design revision carries: a 1280x800 viewport PNG of the built
+ * page, taken in a headless Chromium with the network off.
+ *
+ * The browser is resolved the way Vite is, never as a package dependency: Playwright (or `playwright-core`) from the TARGET root first,
+ * then from this server's own working directory (`createRequire(<dir>/package.json)`, never a global lookup). The operator's rule is
+ * that "no preview image is a fine degraded mode": no browser, a failed launch, a failed capture or a PNG over 1 MiB all publish
+ * WITHOUT a screenshot and say why in the result (`none: <reason>`). That is the one stated degraded mode, reported and never silent,
+ * and it never fails the publish.
+ */
+import { createRequire } from "node:module";
+import path from "node:path";
+export const SCREENSHOT_WIDTH = 1280;
+export const SCREENSHOT_HEIGHT = 800;
+/** The revision route's cap on a decoded screenshot (`MAX_SCREENSHOT_BYTES`, `src/issues/design-limits.ts`): 1 MiB. */
+export const MAX_SCREENSHOT_BYTES = 1024 * 1024;
+/** How long a loaded page may take to say it mounted (`danx-design:ready`) before the capture goes ahead anyway. */
+const READY_WAIT_MS = 5000;
+/** The message a design's harness posts when it has mounted (`DESIGN_FRAME_READY` in `@danxbot/ui`, restated: this package cannot import it). */
+export const READY_MESSAGE = "danx-design:ready";
+const READY_LISTENER = `window.__danxDesignReady = false; window.addEventListener("message", function (e) { ` +
+    `if (e.data && e.data.type === ${JSON.stringify(READY_MESSAGE)}) window.__danxDesignReady = true; });`;
+function none(reason) {
+    return { png_base64: null, screenshot: `none: ${reason}` };
+}
+/** One line of an error: its first line, bounded, so a long Playwright launch log never floods the result. */
+function oneLine(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    const first = text.split("\n")[0].trim();
+    return first.length > 200 ? `${first.slice(0, 200)}...` : first;
+}
+/**
+ * The first of `playwright` / `playwright-core` that resolves from the target root, else from `cwd`. Returns the loaded module, or null
+ * when neither resolves.
+ */
+function resolvePlaywright(rootAbs, cwd) {
+    for (const base of [rootAbs, cwd]) {
+        const req = createRequire(path.join(base, "package.json"));
+        for (const name of ["playwright", "playwright-core"]) {
+            let resolved;
+            try {
+                resolved = req.resolve(name);
+            }
+            catch {
+                continue;
+            }
+            return { module: req(resolved), from: `${name} from ${base}` };
+        }
+    }
+    return null;
+}
+/**
+ * Capture `html` as a 1280x800 viewport PNG (device scale 1, network disabled). The page is `setContent`-ed, then given a short wait
+ * for the harness's ready message (the page has loaded either way). The browser is closed in a `finally` on every path.
+ */
+export async function captureScreenshot(html, where) {
+    let playwright;
+    try {
+        playwright = resolvePlaywright(where.rootAbs, where.cwd);
+    }
+    catch (err) {
+        return none(`playwright could not be loaded: ${oneLine(err)}`);
+    }
+    if (playwright === null) {
+        return none(`neither playwright nor playwright-core resolves from the target root ${where.rootAbs} or from ${where.cwd}`);
+    }
+    let browser;
+    try {
+        browser = await playwright.module.chromium.launch({ headless: true });
+    }
+    catch (err) {
+        return none(`the browser could not be launched (${playwright.from}): ${oneLine(err)}`);
+    }
+    try {
+        const context = await browser.newContext({
+            viewport: { width: SCREENSHOT_WIDTH, height: SCREENSHOT_HEIGHT },
+            deviceScaleFactor: 1,
+            offline: true,
+        });
+        const page = await context.newPage();
+        await page.addInitScript(READY_LISTENER);
+        await page.setContent(html, { waitUntil: "load" });
+        // The page has loaded; a design that never posts ready (it threw, or its harness is older) is still captured as it stands.
+        await page.waitForFunction("window.__danxDesignReady === true", undefined, { timeout: READY_WAIT_MS }).catch(() => undefined);
+        const png = await page.screenshot({ type: "png" });
+        if (png.length > MAX_SCREENSHOT_BYTES) {
+            return none(`the screenshot is ${png.length} bytes, over the ${MAX_SCREENSHOT_BYTES} byte (1 MiB) limit`);
+        }
+        return { png_base64: png.toString("base64"), screenshot: "captured" };
+    }
+    catch (err) {
+        return none(`the screenshot failed: ${oneLine(err)}`);
+    }
+    finally {
+        // A browser that will not close must not fail a publish whose screenshot is already decided.
+        await browser.close().catch((err) => console.error(`[danx-dashboard-mcp] design_publish could not close the browser: ${oneLine(err)}`));
+    }
+}

package/dist/index.js

@@ -106,6 +106,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
 import { planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
+import { designPublish } from "./design-publish.js";
 import { boundedResultText } from "./result-limit.js";
 import { bodyValueSchema, queryValueSchema } from "./types.js";
 import { termsAcceptanceCallHalt, termsHaltFor } from "./terms-halt.js";
@@ -632,6 +633,38 @@ strictTool("attach_file", "Attach a LOCAL file to a card. This server reads and
     primary: z.boolean().optional().describe("Make this attachment the card's single cover (lead image)."),
     ...boardField,
 }, async (args) => guardedJson(() => attachFile(client, args)));
+// ---------------- design_publish (DX-4077) ----------------
+//
+// Agent-specific, so a dedicated tool (R-25): it builds in the agent's OWN checkout with the target repo's own Vite, which the
+// dashboard cannot do (no Vite in its image, no connected repo's source), and uploads the result. Opt-in (`tool-defs.ts`'s
+// `MCP_SERVER_OPT_IN_TOOLS`) and granted to no profile here: a default tool would add its schema to every default-all role's first
+// turn, and a role with no worktree or toolchain can only fail it. The package takes no `vite` or `playwright` dependency: both are
+// resolved from the target repo at run time (`design-build.ts`, `design-screenshot.ts`).
+strictTool("design_publish", "Build a design against this repo's REAL components with the repo's own Vite and publish it as a revision of a Design card. " +
+    "The design is a directory holding `Design.tsx` (a default-exported React component) plus any helpers; it may be a whole " +
+    "front-end app, and how to split its states is your call. Without `card_id` this creates the Design card (needs `title` and " +
+    "`summary`, and a connected plan: it files the card with plan \"mine\", so connect one with plan_connect first); with `card_id`, the " +
+    "next revision goes on that card and `title`, `summary` and `description` are refused. Returns `{card_id, revision_no, dashboard_url, local_html_path, " +
+    "screenshot}`: `local_html_path` is the built page, written before the upload so you can open it yourself; `screenshot` is " +
+    "`captured` (1280x800) or `none: <reason>` (no Playwright in the repo: the publish still succeeds). Build errors and a " +
+    "refused revision (400, 413) come back verbatim; a refusal after the card was created carries its `card_id`: fix the " +
+    "design and call again with it. Limits: the frame has no network, so a component that fetches its own data fails inside " +
+    "it (use fixture props); React only; targets are edited in Settings > Board > General, never in a file.", {
+    target: z.string().min(1).describe("A design target's name, as declared in Settings > Board > General (Design targets)."),
+    dir: z
+        .string()
+        .min(1)
+        .describe("The design directory: absolute, or relative to this server's cwd. Inside the target's root, holding `Design.tsx`."),
+    card_id: z.string().min(1).optional().describe("Add a revision to this Design card; omit to create one."),
+    title: z.string().min(1).optional().describe("The new card's title. Required without `card_id`; refused with it."),
+    summary: z.string().min(1).optional().describe("The new card's summary. Required without `card_id`; refused with it."),
+    description: z.string().optional().describe("The new card's description; default empty. Refused with `card_id`."),
+    board: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Board id `<repo>:<slug>` for the new card; omit for this server's board. With `card_id` the card's own board is used."),
+}, async (args) => guardedJson(() => designPublish(client, args, { serverBoard: config.board, baseUrl: config.baseUrl, cwd: process.cwd() })));
 // ---------------- request_permission (DX-4434, parent DX-4432) ----------------
 strictTool("request_permission", "Ask a person to grant this key ONE MORE permission. Call it when a call was refused `403 forbidden` naming a " +
     "`permission`, or when you know you need one more. It returns AT ONCE with `{state, approvalUrl, confirmCode, " +

package/dist/listen.js

@@ -79,6 +79,11 @@ function isRecord(value) {
 function isCappedText(value) {
     return isRecord(value) && typeof value.text === "string" && typeof value.truncated === "boolean";
 }
+/** DX-4078 - hand-copied from `DESIGN_DECISION_OUTCOMES` (`src/issues/view-types.ts`): this published package cannot import danxbot source. */
+const DESIGN_OUTCOMES = ["approved", "rejected", "changes_requested"];
+function isDesignOutcome(value) {
+    return typeof value === "string" && DESIGN_OUTCOMES.includes(value);
+}
 /**
  * DX-3880 — the part `solution_answered` and `problem_answer_changed` share: the
  * decision's `outcome` and the either/or body it implies. A rejection (the
@@ -188,6 +193,20 @@ export function invalidEventReason(value) {
             if (typeof d.review_url !== "string")
                 return "detail.review_url is not a string";
             return isCappedText(d.excerpt) ? null : "detail.excerpt is not capped text";
+        // DX-4078: the operator's verdict on a design revision. An outcome this listener does not know is refused, never rendered as the bare
+        // kind line, which would name no outcome and no note and leave the agent to re-read the card. `rejected` and `changes_requested` always
+        // carry their note (the table CHECK); `approved` may carry none.
+        case "design_decided": {
+            if (typeof d.decision_id !== "number")
+                return "detail.decision_id is not a number";
+            if (typeof d.revision_no !== "number")
+                return "detail.revision_no is not a number";
+            if (!isDesignOutcome(d.outcome))
+                return 'detail.outcome is not "approved", "rejected" or "changes_requested"';
+            if (d.note === null)
+                return d.outcome === "approved" ? null : `detail.note (the ${d.outcome} reason) is null`;
+            return isCappedText(d.note) ? null : "detail.note is not null or capped text";
+        }
         default:
             return null;
     }
@@ -266,6 +285,16 @@ function describe(event) {
         // DX-4622: the agent must act on the review, so the line names who, where, and what to do next.
         case "pull_request_changes_requested":
             return `${who}: ${d.reviewer} requested changes on the pull request (${d.review_url})${d.excerpt.text === "" ? "" : `: ${quoted(d.excerpt)}`}. Address the review, push, and reply on the pull request`;
+        // DX-4078: names the outcome, the revision and the note, and what the agent does next, so it never has to re-read the card to learn the verdict.
+        case "design_decided": {
+            const note = d.note;
+            const revision = `revision ${d.revision_no} of the design`;
+            if (d.outcome === "approved")
+                return `${who} APPROVED ${revision}${note === null ? "" : ` — note: ${quoted(note)}`}. The design is closed; build from it`;
+            if (d.outcome === "rejected")
+                return `${who} REJECTED ${revision} — reason: ${quoted(note)}. The design is closed; do not continue it`;
+            return `${who} requested changes on ${revision} — ${quoted(note)}. Publish a new revision that addresses it`;
+        }
         default:
             // A kind newer than this listener still produces a line: an event the
             // agent is never told about is exactly the failure this reader prevents.

package/dist/tool-access.js

@@ -43,6 +43,10 @@ export const TOOL_ACCESS = {
     danxbot_api_spec: BOOTSTRAP,
     // `POST /api/issues/:id/attachments`
     attach_file: needs("cards.edit"),
+    // DX-4077 - builds in the agent's own checkout, then `POST /api/issues/:id/design/revisions` (`cards.edit`, DX-4076). The routes it
+    // reads on the way (`GET /api/boards/:id`, `GET /api/repos/:id`, `GET /api/issues/:id`) and the card it creates are separate
+    // checks on the dashboard whose refusals come back verbatim.
+    design_publish: needs("cards.edit"),
     // DX-4233 - the plugin's relay waits on the session's plan events here: it opens the listener ticket
     // (`POST /api/plan-sessions/me/stream-ticket`) and heartbeats (`.../me/heartbeat`), both `plans.view`.
     plan_events_wait: operatorSessionNeeds("plans.view"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.278",
+  "version": "0.1.280",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, request_permission, attach_file, and danxbot_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",