@codepress/design-kit 0.12.0 → 0.13.0

package/README.md

@@ -392,6 +392,7 @@ design-kit init            [--root dir] [--dry-run] [--force] [--workflow-only]
 design-kit upload          --dir kit [--config f] [--branch b] [--sha commit]
 design-kit fetch           [--branch b] [--out dir] [--config f] [--repo owner/name]
                            [--token-file f]
+design-kit fetch           --url download-url --sha commit [--branch b] [--out dir]
 design-kit latest          [--branch b] [--config f] [--repo owner/name] [--token-file f]
 design-kit capture stories [--config f] [--out dir] [--storybook-dir dir]
                            [--only id,... | --only-file f] [--base previous-kit]
@@ -411,8 +412,19 @@ design-kit storybook-guide
 kit (`codepress`, `s3` and `r2`; with `github` it exits 2, since the
 workflow's upload step does it). `fetch` downloads the newest kit once per
 commit, into `$TMPDIR/design-kit-<sha>` unless `--out` says otherwise, and
-prints `path=`, `sha=` and `branch=`; a second `fetch` of the same commit
-downloads nothing. `latest` prints the newest kit's `sha=` and `created=`.
+prints `path=`, `sha=`, `branch=` and the kit's summary line (as `kit info`
+prints it); a second `fetch` of the same commit downloads nothing.
+`fetch --url <download_url> --sha <commit>` needs no key and no config: it
+installs from a download URL already looked up (with `codepress` storage, the
+`download_url` of the latest route, read through the CodePress Platform MCP)
+into the same cache folder, which it reuses when complete. It streams the zip to
+a scratch folder beside the target, unzips it there, checks that
+`manifest.json` names `--sha`, and renames it into place, so a refused or
+expired URL (`forbidden`), a broken zip (`bad_archive`) or another commit's kit
+(`sha_mismatch`) exits 1 with one line and leaves nothing behind, as does an
+`--out` folder that holds files but no kit (`out_not_empty`, left untouched). Of two
+fetches racing for one commit, the loser keeps the winner's folder. The URL's
+query string is never printed. `latest` prints the newest kit's `sha=` and `created=`.
 Without `--branch` they read the default branch. A store's refusal keeps its
 name (`forbidden`, `no_kit`, `repo_not_connected`, …), a store that cannot be
 reached is `kit_storage_unavailable`, and both exit 1.
@@ -527,8 +539,16 @@ node kit.mjs find "transfer app"     # the words on screen work too
 node kit.mjs show <id> [--full]      # path, size and an outline (≤ 2 KB) or the markup
 node kit.mjs compose --frame route:dashboard@1280 --slot main=new.html \
   [--theme light|dark] [--show-new] [--css pruned|full] --out page.html
+node kit.mjs figure --img shot.png [--href '#cp-page:<key>'] [--caption text] \
+  [--alt text] [--width px] --out figure.html
 ```
 
+`figure` needs no kit: it writes a self-contained `<figure>` fragment with
+the `.png`, `.jpg` or `.webp` image as a data URI, inside a link when `--href`
+is given (a fragment such as `#cp-page:<key>`, which links a plan page to a
+screen page, or a relative link), and the caption and alt text escaped. It
+warns on stderr when the image is over 1 MB.
+
 `info` prints one line, such as
 `480e11d built 2026-11-15T18:58:59.954Z · stories 12821 · routes 133 · failed 13`,
 and names the failed ids from `gaps.json` when there are five or fewer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Capture your Storybook and real app pages as a static design kit, and compose self-contained mockups from it",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -35,9 +35,13 @@ const USAGE = `usage: design-kit <command> [options]
                     (codepress, s3 or r2; github uploads in the workflow)
       --dir <kit> [--config <file>] [--branch <name>] [--sha <commit>]
   fetch             download the newest kit, once per commit (cached under
-                    $TMPDIR/design-kit-<sha>); prints path=, sha= and branch=
+                    $TMPDIR/design-kit-<sha>); prints path=, sha=, branch=
+                    and the kit's summary line
       [--branch <name>] [--out <dir>] [--config <file>] [--repo <owner/name>]
       [--token-file <path>]   codepress: the API key, if not CODEPRESS_API_KEY
+      --url <download_url> --sha <commit> [--branch <name>] [--out <dir>]
+                    install from the download_url of the latest route (read
+                    through the Platform MCP): no key and no config needed
   latest            print the newest kit's sha= and created=
       [--branch <name>] [--config <file>] [--repo <owner/name>]
       [--token-file <path>]
@@ -245,7 +249,9 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         ...(command === "upload"
           ? { dir: "value", sha: "value" }
           : { "token-file": "value" }),
-        ...(command === "fetch" ? { out: "value" } : {}),
+        ...(command === "fetch"
+          ? { out: "value", url: "value", sha: "value" }
+          : {}),
       };
       const options = parse(argv.slice(1), spec);
       const storage = await import("./storage/index.mjs");

package/src/kit.d.ts

@@ -134,3 +134,27 @@ export function run(
 
 /** Whether this file is the script node was started with. */
 export function isMain(moduleUrl?: string, script?: string): boolean;
+
+/**
+ * The kit's one-line summary, as `kit info` prints it:
+ * `sha7 built <iso> · stories N · routes N · failed N` (the failed ids when
+ * there are five or fewer).
+ */
+export function kitSummaryLine(kit: Kit): string;
+
+/** Image bytes above which `kit figure` warns: 1 MB. */
+export const FIGURE_WARN_BYTES: number;
+
+/**
+ * `kit figure`'s fragment: a `<figure>` with the image as a data URI, inside
+ * `<a href>` when `href` is given (a fragment such as `#cp-page:<key>` or a
+ * relative link), and the caption escaped. `width` is CSS pixels.
+ */
+export function figureHtml(options: {
+  image: Uint8Array;
+  type: "image/png" | "image/jpeg" | "image/webp";
+  href?: string;
+  caption?: string;
+  alt?: string;
+  width?: string | number;
+}): string;

package/src/kit.mjs

@@ -8,6 +8,8 @@
  *   node kit.mjs show <id> [--full]
  *   node kit.mjs compose --frame <id> [--slot <name>=<file>]… [--theme light|dark]
  *                        [--show-new] [--css pruned|full] --out <file>
+ *   node kit.mjs figure --img <file> [--href <#cp-page:key>] [--caption <text>]
+ *                       [--alt <text>] [--width <px>] --out <file>
  *
  * `--kit <dir>` (or DESIGN_KIT_DIR) points at a kit; the default is the
  * folder this file sits in. Format: the @codepress/design-kit README.
@@ -2168,12 +2170,12 @@ function failedIds(dir) {
 }
 
 /**
- * One line: `sha7 built <iso> · stories N · routes N · failed N`, with the
- * failed ids when there are five or fewer. `json` prints manifest.json.
+ * The kit's one-line summary: `sha7 built <iso> · stories N · routes N ·
+ * failed N`, with the failed ids when there are five or fewer. `kit info`
+ * prints it, and so does `design-kit fetch` after `path=`.
  */
-function infoText(kit, json) {
-  const manifest = kit.manifest ?? { missing: "manifest.json" };
-  if (json) return JSON.stringify(manifest, null, 2);
+export function kitSummaryLine(kit) {
+  const manifest = kit.manifest ?? {};
   const routes = kit.rows.filter((row) => rowSource(row) === "routes").length;
   const sha = typeof manifest.sha === "string" ? manifest.sha.slice(0, 7) : "";
   const built =
@@ -2192,6 +2194,99 @@ function infoText(kit, json) {
   ].join(" · ");
 }
 
+/** `info`: the summary line; `json` prints manifest.json. */
+function infoText(kit, json) {
+  if (json)
+    return JSON.stringify(
+      kit.manifest ?? { missing: "manifest.json" },
+      null,
+      2,
+    );
+  return kitSummaryLine(kit);
+}
+
+// ── figure ──────────────────────────────────────────────────────────────────
+
+/** Image types `figure` embeds, by file extension. */
+const FIGURE_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+};
+
+/** Above this many image bytes `figure` warns: the page carries them all. */
+export const FIGURE_WARN_BYTES = 1024 * 1024;
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/**
+ * A self-contained `<figure>`: the image as a data URI, inside a link when
+ * `href` is given, with an escaped caption. `href` must be a fragment or a
+ * relative link (`#cp-page:<key>` links plan pages); `width` is CSS pixels.
+ */
+export function figureHtml({ image, type, href, caption, alt, width }) {
+  if (
+    href !== undefined &&
+    (!href || !isSafeUrl(href) || /^data:/i.test(href.trim()))
+  )
+    throw new KitError(
+      `--href ${href}: use a fragment such as '#cp-page:<key>' or a relative link`,
+    );
+  let style = "max-width:100%;height:auto;display:block";
+  if (width !== undefined) {
+    const px = Number(width);
+    if (!(Number.isFinite(px) && px > 0))
+      throw new KitError(
+        `--width ${width}: use a positive number of CSS pixels`,
+      );
+    style = `width:${px}px;${style}`;
+  }
+  const src = `data:${type};base64,${image.toString("base64")}`;
+  let img = `<img src="${src}" alt="${escapeHtml(alt ?? caption ?? "")}" style="${style}">`;
+  if (href !== undefined) img = `<a href="${escapeHtml(href)}">${img}</a>`;
+  const figcaption =
+    caption === undefined
+      ? ""
+      : `\n  <figcaption>${escapeHtml(caption)}</figcaption>`;
+  return `<figure style="margin:0">\n  ${img}${figcaption}\n</figure>\n`;
+}
+
+/** `figure --img <file> --out <file>`: writes the fragment; no kit needed. */
+function figureCommand(options, io) {
+  if (!options.img)
+    throw new KitError("figure needs --img <file.png|jpg|webp>");
+  if (!options.out) throw new KitError("figure needs --out <file>");
+  const file = resolve(options.img);
+  const type = FIGURE_TYPES[extname(file).toLowerCase()];
+  if (!type)
+    throw new KitError(`--img ${options.img}: use a .png, .jpg or .webp file`);
+  if (!existsSync(file))
+    throw new KitError(`--img ${options.img}: no such file`);
+  const image = readFileSync(file);
+  const html = figureHtml({
+    image,
+    type,
+    href: options.href,
+    caption: options.caption,
+    alt: options.alt,
+    width: options.width,
+  });
+  if (image.length > FIGURE_WARN_BYTES)
+    io.err(
+      `kit: warning: ${options.img} is ${formatBytes(image.length)}; the page carries it all (shrink it below 1 MB)`,
+    );
+  const out = resolve(options.out);
+  writeFileSync(out, html);
+  io.out(`${out}  ${formatBytes(Buffer.byteLength(html))}`);
+}
+
 // ── CLI ─────────────────────────────────────────────────────────────────────
 
 const USAGE = `usage: kit.mjs [--kit <dir>] <command>
@@ -2201,7 +2296,10 @@ const USAGE = `usage: kit.mjs [--kit <dir>] <command>
   show <id> [--full]           path, size and an outline (--full: the markup)
   compose --frame <id> [--slot <name>=<file>]… [--theme light|dark] [--show-new] [--css pruned|full] --out <file>
                                --css full keeps every rule of the kit's CSS; the default
-                               keeps only rules the page's classes and ids can use`;
+                               keeps only rules the page's classes and ids can use
+  figure --img <file.png|jpg|webp> [--href '#cp-page:<key>'] [--caption <text>] [--alt <text>] [--width <px>] --out <file>
+                               a self-contained <figure>: the image as a data URI, linked when
+                               --href is given, the caption escaped (no kit needed)`;
 
 function parseArgs(argv) {
   const options = { slots: [], positional: [] };
@@ -2219,6 +2317,11 @@ function parseArgs(argv) {
     else if (arg === "--theme") options.theme = value();
     else if (arg === "--out") options.out = value();
     else if (arg === "--css") options.css = value();
+    else if (arg === "--img") options.img = value();
+    else if (arg === "--href") options.href = value();
+    else if (arg === "--caption") options.caption = value();
+    else if (arg === "--alt") options.alt = value();
+    else if (arg === "--width") options.width = value();
     else if (arg === "--full") options.full = true;
     else if (arg === "--json") options.json = true;
     else if (arg === "--show-new") options.showNew = true;
@@ -2243,6 +2346,11 @@ export function run(
       io.out(USAGE);
       return command || options.help ? 0 : 2;
     }
+    if (command === "figure") {
+      if (rest.length) throw new KitError(`figure takes no ${rest[0]}`);
+      figureCommand(options, io);
+      return 0;
+    }
     const dir = resolve(options.kit ?? env.DESIGN_KIT_DIR ?? defaultDir);
     const kit = loadKit(dir);
     if (command === "info") {

package/src/storage/index.mjs

@@ -6,6 +6,8 @@
  *     upload({dir, branch, sha}) → {sha, branch, sizeBytes}
  *     fetch({branch, out})      → {path, sha, branch, cached}
  *
+ * `fetchFromUrl` (url.mjs) installs a kit from a download URL with no store.
+ *
  * `github` (the default) is a GitHub Actions artifact; `codepress` is
  * CodePress; `s3` and `r2` are the user's own bucket. The commands
  * `design-kit upload`, `fetch` and `latest` are here too.
@@ -18,6 +20,8 @@ import { bucketStorage } from "./bucket.mjs";
 import { codepressStorage } from "./codepress.mjs";
 import { findRepo, originDefaultBranch } from "./common.mjs";
 import { githubStorage } from "./github.mjs";
+import { fetchFromUrl } from "./url.mjs";
+import { kitSummaryLine, loadKit } from "../kit.mjs";
 
 export { StorageError } from "./common.mjs";
 
@@ -99,25 +103,47 @@ export async function uploadCommand(
 /**
  * `design-kit fetch [--branch b] [--out dir]`: downloads the newest kit
  * (once per commit: it is cached under $TMPDIR/design-kit-<sha>) and prints
- * `path=`, `sha=` and `branch=`.
+ * `path=`, `sha=`, `branch=` and the kit's summary line.
+ *
+ * `--url <download_url> --sha <commit>` installs from a download URL already
+ * looked up (no credential, no config): same cache, same output.
  */
 export async function fetchCommand(
   options,
   { env = process.env, gh, aws } = {},
 ) {
-  const config = loadConfig(options.config);
-  const storage = storageOf(config);
-  const store = storageFor(
-    storage,
-    contextFor(options, config, { env, gh, aws }),
-  );
-  const kit = await store.fetch({
-    branch: readBranch(options, storage, config.configDir),
-    out: options.out,
-  });
+  let kit;
+  if (options.url !== undefined || options.sha !== undefined) {
+    if (!options.url || !options.sha)
+      throw new ConfigError("fetch --url <download_url> needs --sha <commit>");
+    for (const name of ["config", "repo", "token-file"])
+      if (options[name] !== undefined)
+        throw new ConfigError(
+          `fetch --url takes no --${name}: it reads no store`,
+        );
+    kit = await fetchFromUrl({
+      url: options.url,
+      sha: options.sha,
+      branch: options.branch,
+      out: options.out,
+      env,
+    });
+  } else {
+    const config = loadConfig(options.config);
+    const storage = storageOf(config);
+    const store = storageFor(
+      storage,
+      contextFor(options, config, { env, gh, aws }),
+    );
+    kit = await store.fetch({
+      branch: readBranch(options, storage, config.configDir),
+      out: options.out,
+    });
+  }
   console.log(`path=${kit.path}`);
   console.log(`sha=${kit.sha}`);
   if (kit.branch) console.log(`branch=${kit.branch}`);
+  console.log(kitSummaryLine(loadKit(kit.path)));
   return 0;
 }
 

package/src/storage/url.mjs

@@ -0,0 +1,174 @@
+/**
+ * `design-kit fetch --url <download_url> --sha <commit>`: installs a kit
+ * from a download URL someone else already looked up (the `download_url` of
+ * `GET /design-kits/repos/{owner}/{repo}/latest`, read through the Platform
+ * MCP), with no credential and no config.
+ *
+ * The kit lands where the key path puts it, `$TMPDIR/design-kit-<sha>`, and a
+ * complete folder there is reused without downloading. Otherwise the zip is
+ * streamed to a scratch folder beside the target, unzipped there with the
+ * package's own reader, checked (its manifest.json must name `sha`), and
+ * renamed into place in one step. A fetch that loses a race to another for
+ * the same commit keeps the winner's folder. A failure leaves nothing behind.
+ */
+import {
+  createWriteStream,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+} from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import { dirname, join, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+
+import { StorageError, checkSha, isKit, kitCacheDir } from "./common.mjs";
+import { unzipTo } from "./zip.mjs";
+
+/** How long the download may stall before it counts as failed. */
+const DOWNLOAD_TIMEOUT_MS = Number(
+  process.env.DESIGN_KIT_REQUEST_TIMEOUT_MS || 120_000,
+);
+
+/** What an S3- or R2-style refusal is called, by status. */
+const REFUSED = {
+  400: "bad_request",
+  401: "unauthorized",
+  403: "forbidden",
+  404: "not_found",
+  410: "expired",
+};
+
+/** The query string of a URL replaced by `?…`, so a signature never prints. */
+export function redactUrl(url) {
+  return String(url).replace(/\?.*$/s, "?…");
+}
+
+/** Streams `url` into `file`. A non-2xx answer or a broken stream throws. */
+function download(url, file) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new StorageError("invalid_url", "--url is not a URL");
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+    throw new StorageError(
+      "invalid_url",
+      "--url must be an https: download URL",
+    );
+  const client = parsed.protocol === "http:" ? http : https;
+  return new Promise((resolvePromise, reject) => {
+    const req = client.get(parsed, { timeout: DOWNLOAD_TIMEOUT_MS }, (res) => {
+      const status = res.statusCode ?? 0;
+      if (status < 200 || status >= 300) {
+        res.resume();
+        const code =
+          REFUSED[status] ??
+          (status >= 500 ? "kit_storage_unavailable" : `http_${status}`);
+        const hint =
+          status === 403 || status === 400 || status === 410
+            ? "; the download URL may have expired, so ask for a fresh one"
+            : "";
+        reject(
+          new StorageError(
+            code,
+            `downloading ${redactUrl(url)} was refused (${status})${hint}`,
+          ),
+        );
+        return;
+      }
+      pipeline(res, createWriteStream(file)).then(resolvePromise, (error) =>
+        reject(
+          new StorageError(
+            "download_failed",
+            `downloading ${redactUrl(url)} broke off (${error.code ?? error.message})`,
+          ),
+        ),
+      );
+    });
+    req.on("timeout", () => req.destroy(new Error("no answer in time")));
+    req.on("error", (error) =>
+      reject(
+        new StorageError(
+          "kit_storage_unavailable",
+          `could not reach ${parsed.host} (${error.code ?? error.message})`,
+        ),
+      ),
+    );
+  });
+}
+
+/** Nothing when manifest.json's `sha` starts with `sha`, else a StorageError. */
+function checkManifestSha(dir, sha) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
+  } catch {
+    throw new StorageError(
+      "not_a_kit",
+      "the download has no readable manifest.json",
+    );
+  }
+  const named =
+    typeof manifest?.sha === "string" ? manifest.sha.toLowerCase() : "";
+  const wanted = sha.toLowerCase();
+  // A short --sha may name the manifest's full sha, never the other way round.
+  if (!named || !named.startsWith(wanted))
+    throw new StorageError(
+      "sha_mismatch",
+      `the downloaded kit is of ${named.slice(0, 12) || "no commit"}, not ${wanted.slice(0, 12)}`,
+    );
+}
+
+/**
+ * Installs the kit of commit `sha` from `url` into `out` (default
+ * `$TMPDIR/design-kit-<sha>`): `{path, sha, branch, cached}`.
+ */
+export async function fetchFromUrl({
+  url,
+  sha,
+  branch,
+  out,
+  env = process.env,
+}) {
+  if (!url)
+    throw new StorageError("invalid_url", "--url needs the kit's download URL");
+  checkSha(sha, "--sha");
+  const path = resolve(out ?? kitCacheDir(sha, env));
+  const result = { path, sha, branch };
+  if (isKit(path)) return { ...result, cached: true };
+  mkdirSync(dirname(path), { recursive: true });
+  const scratch = mkdtempSync(`${path}.partial-`);
+  try {
+    const zipFile = join(scratch, "kit.zip");
+    const unpacked = join(scratch, "kit");
+    await download(url, zipFile);
+    try {
+      unzipTo(readFileSync(zipFile), unpacked);
+    } catch (error) {
+      throw new StorageError(
+        "bad_archive",
+        `the download is not a whole kit zip (${error.message})`,
+      );
+    }
+    checkManifestSha(unpacked, sha);
+    try {
+      renameSync(unpacked, path);
+    } catch (error) {
+      // Another fetch of the same commit got there first: keep its folder.
+      if (isKit(path)) return { ...result, cached: true };
+      if (error.code === "ENOTEMPTY" || error.code === "EEXIST")
+        throw new StorageError(
+          "out_not_empty",
+          `${path} exists and is not a kit; choose another --out`,
+        );
+      throw error;
+    }
+    return { ...result, cached: false };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}