@spectratools/graphic-designer-cli 0.3.1 → 0.4.0

package/dist/publish/index.d.ts

@@ -1,8 +1,4 @@
-interface RetryPolicy {
-    maxRetries: number;
-    baseMs: number;
-    maxMs: number;
-}
+import { RetryOptions } from '@spectratools/cli-shared/middleware';
 
 type GitHubPublishOptions = {
     imagePath: string;
@@ -12,19 +8,37 @@ type GitHubPublishOptions = {
     branch?: string;
     token?: string;
     commitMessage?: string;
-    retryPolicy?: RetryPolicy;
+    retryPolicy?: RetryOptions;
 };
 type GitHubPublishResult = {
     target: 'github';
     repo: string;
     branch: string;
-    attempts: number;
     files: Array<{
         path: string;
         htmlUrl?: string;
         sha?: string;
     }>;
 };
+/**
+ * Publish rendered design artifacts to a GitHub repository.
+ *
+ * Uploads the PNG image and sidecar `.meta.json` metadata to the specified
+ * repository via the GitHub Contents API. Files are placed under
+ * {@link GitHubPublishOptions.pathPrefix} (defaults to `"artifacts"`). If a
+ * file already exists at the destination it is updated in-place (its SHA is
+ * fetched first for the update).
+ *
+ * Requires a GitHub token — either passed via
+ * {@link GitHubPublishOptions.token} or resolved from the `GITHUB_TOKEN`
+ * environment variable.
+ *
+ * @param options - Publish configuration including file paths, target repo,
+ *   branch, commit message, and optional retry policy.
+ * @returns A {@link GitHubPublishResult} with the repo, branch, and per-file
+ *   metadata (path, SHA, HTML URL).
+ * @throws When no GitHub token is available or the API request fails.
+ */
 declare function publishToGitHub(options: GitHubPublishOptions): Promise<GitHubPublishResult>;
 
 type GistPublishOptions = {
@@ -35,15 +49,30 @@ type GistPublishOptions = {
     filenamePrefix?: string;
     public?: boolean;
     token?: string;
-    retryPolicy?: RetryPolicy;
+    retryPolicy?: RetryOptions;
 };
 type GistPublishResult = {
     target: 'gist';
     gistId: string;
     htmlUrl: string;
-    attempts: number;
     files: string[];
 };
+/**
+ * Publish rendered design artifacts to a GitHub Gist.
+ *
+ * Creates (or updates, when {@link GistPublishOptions.gistId} is set) a gist
+ * containing the PNG image as a base64 text file, the sidecar `.meta.json`
+ * metadata, and a Markdown README with an embedded preview.
+ *
+ * Requires a GitHub token — either passed via {@link GistPublishOptions.token}
+ * or resolved from the `GITHUB_TOKEN` environment variable.
+ *
+ * @param options - Publish configuration including file paths, gist settings,
+ *   and optional retry policy.
+ * @returns A {@link GistPublishResult} with the gist ID, URL, attempt count,
+ *   and list of created file names.
+ * @throws When no GitHub token is available or the API request fails.
+ */
 declare function publishToGist(options: GistPublishOptions): Promise<GistPublishResult>;
 
 export { type GistPublishOptions, type GistPublishResult, type GitHubPublishOptions, type GitHubPublishResult, publishToGist, publishToGitHub };

package/dist/publish/index.js

@@ -1,38 +1,8 @@
 // src/publish/github.ts
 import { readFile } from "fs/promises";
 import { basename, posix } from "path";
-
-// src/utils/retry.ts
-var DEFAULT_RETRY_POLICY = {
-  maxRetries: 3,
-  baseMs: 500,
-  maxMs: 4e3
-};
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-async function withRetry(operation, policy = DEFAULT_RETRY_POLICY) {
-  let attempt = 0;
-  let lastError;
-  while (attempt <= policy.maxRetries) {
-    try {
-      const value = await operation();
-      return { value, attempts: attempt + 1 };
-    } catch (error) {
-      lastError = error;
-      if (attempt >= policy.maxRetries) {
-        break;
-      }
-      const backoff = Math.min(policy.baseMs * 2 ** attempt, policy.maxMs);
-      const jitter = Math.floor(Math.random() * 125);
-      await sleep(backoff + jitter);
-      attempt += 1;
-    }
-  }
-  throw lastError;
-}
-
-// src/publish/github.ts
+import { withRetry } from "@spectratools/cli-shared/middleware";
+import { HttpError, createHttpClient } from "@spectratools/cli-shared/utils";
 function requireGitHubToken(token) {
   const resolved = token ?? process.env.GITHUB_TOKEN;
   if (!resolved) {
@@ -40,56 +10,18 @@ function requireGitHubToken(token) {
   }
   return resolved;
 }
-async function githubJson(path, init, token, retryPolicy) {
-  return withRetry(async () => {
-    const response = await fetch(`https://api.github.com${path}`, {
-      ...init,
-      headers: {
-        Accept: "application/vnd.github+json",
-        Authorization: `Bearer ${token}`,
-        "User-Agent": "spectratools-graphic-designer",
-        ...init.headers
-      }
-    });
-    if (!response.ok) {
-      const text = await response.text();
-      throw new Error(
-        `GitHub API ${path} failed (${response.status}): ${text || response.statusText}`
-      );
-    }
-    return await response.json();
-  }, retryPolicy);
-}
-async function githubJsonMaybe(path, token, retryPolicy) {
-  const { value, attempts } = await withRetry(async () => {
-    const response = await fetch(`https://api.github.com${path}`, {
-      headers: {
-        Accept: "application/vnd.github+json",
-        Authorization: `Bearer ${token}`,
-        "User-Agent": "spectratools-graphic-designer"
-      }
-    });
-    if (response.status === 404) {
-      return { found: false };
-    }
-    if (!response.ok) {
-      const text = await response.text();
-      throw new Error(
-        `GitHub API ${path} failed (${response.status}): ${text || response.statusText}`
-      );
-    }
-    const json = await response.json();
-    return { found: true, value: json };
-  }, retryPolicy);
-  if (!value.found) {
-    return { found: false, attempts };
+var DEFAULT_RETRY = {
+  maxRetries: 3,
+  baseMs: 500,
+  maxMs: 4e3
+};
+var github = createHttpClient({
+  baseUrl: "https://api.github.com",
+  defaultHeaders: {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "spectratools-graphic-designer"
   }
-  return {
-    found: true,
-    value: value.value,
-    attempts
-  };
-}
+});
 function parseRepo(repo) {
   const [owner, name] = repo.split("/");
   if (!owner || !name) {
@@ -105,9 +37,25 @@ function normalizePath(pathPrefix, filename) {
   const trimmed = (pathPrefix ?? "artifacts").replace(/^\/+|\/+$/gu, "");
   return posix.join(trimmed, filename);
 }
+async function githubJsonMaybe(path, token, retry) {
+  return withRetry(async () => {
+    try {
+      const value = await github.request(path, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      return { found: true, value };
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 404) {
+        return { found: false };
+      }
+      throw err;
+    }
+  }, retry);
+}
 async function publishToGitHub(options) {
   const token = requireGitHubToken(options.token);
   const branch = options.branch ?? "main";
+  const retry = options.retryPolicy ?? DEFAULT_RETRY;
   const commitMessage = options.commitMessage ?? "chore(graphic-designer): publish deterministic artifacts";
   const [imageBuffer, metadataBuffer] = await Promise.all([
     readFile(options.imagePath),
@@ -125,16 +73,10 @@ async function publishToGitHub(options) {
       content: metadataBuffer.toString("base64")
     }
   ];
-  let totalAttempts = 0;
   const files = [];
   for (const upload of uploads) {
     const existingPath = `${toApiContentPath(options.repo, upload.destination)}?ref=${encodeURIComponent(branch)}`;
-    const existing = await githubJsonMaybe(
-      existingPath,
-      token,
-      options.retryPolicy
-    );
-    totalAttempts += existing.attempts;
+    const existing = await githubJsonMaybe(existingPath, token, retry);
     const body = {
       message: `${commitMessage} (${basename(upload.sourcePath)})`,
       content: upload.content,
@@ -142,27 +84,24 @@ async function publishToGitHub(options) {
       sha: existing.value?.sha
     };
     const putPath = toApiContentPath(options.repo, upload.destination);
-    const published = await githubJson(
-      putPath,
-      {
+    const published = await withRetry(
+      () => github.request(putPath, {
         method: "PUT",
-        body: JSON.stringify(body)
-      },
-      token,
-      options.retryPolicy
+        body,
+        headers: { Authorization: `Bearer ${token}` }
+      }),
+      retry
     );
-    totalAttempts += published.attempts;
     files.push({
       path: upload.destination,
-      ...published.value.content?.sha ? { sha: published.value.content.sha } : {},
-      ...published.value.content?.html_url ? { htmlUrl: published.value.content.html_url } : {}
+      ...published.content?.sha ? { sha: published.content.sha } : {},
+      ...published.content?.html_url ? { htmlUrl: published.content.html_url } : {}
     });
   }
   return {
     target: "github",
     repo: options.repo,
     branch,
-    attempts: totalAttempts,
     files
   };
 }
@@ -170,6 +109,8 @@ async function publishToGitHub(options) {
 // src/publish/gist.ts
 import { readFile as readFile2 } from "fs/promises";
 import { basename as basename2 } from "path";
+import { withRetry as withRetry2 } from "@spectratools/cli-shared/middleware";
+import { createHttpClient as createHttpClient2 } from "@spectratools/cli-shared/utils";
 function requireGitHubToken2(token) {
   const resolved = token ?? process.env.GITHUB_TOKEN;
   if (!resolved) {
@@ -177,28 +118,21 @@ function requireGitHubToken2(token) {
   }
   return resolved;
 }
-async function gistJson(path, init, token, retryPolicy) {
-  return withRetry(async () => {
-    const response = await fetch(`https://api.github.com${path}`, {
-      ...init,
-      headers: {
-        Accept: "application/vnd.github+json",
-        Authorization: `Bearer ${token}`,
-        "User-Agent": "spectratools-graphic-designer",
-        ...init.headers
-      }
-    });
-    if (!response.ok) {
-      const text = await response.text();
-      throw new Error(
-        `GitHub Gist API ${path} failed (${response.status}): ${text || response.statusText}`
-      );
-    }
-    return await response.json();
-  }, retryPolicy);
-}
+var DEFAULT_RETRY2 = {
+  maxRetries: 3,
+  baseMs: 500,
+  maxMs: 4e3
+};
+var github2 = createHttpClient2({
+  baseUrl: "https://api.github.com",
+  defaultHeaders: {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "spectratools-graphic-designer"
+  }
+});
 async function publishToGist(options) {
   const token = requireGitHubToken2(options.token);
+  const retry = options.retryPolicy ?? DEFAULT_RETRY2;
   const [imageBuffer, metadataBuffer] = await Promise.all([
     readFile2(options.imagePath),
     readFile2(options.metadataPath)
@@ -236,21 +170,19 @@ async function publishToGist(options) {
   };
   const endpoint = options.gistId ? `/gists/${options.gistId}` : "/gists";
   const method = options.gistId ? "PATCH" : "POST";
-  const published = await gistJson(
-    endpoint,
-    {
+  const published = await withRetry2(
+    () => github2.request(endpoint, {
       method,
-      body: JSON.stringify(payload)
-    },
-    token,
-    options.retryPolicy
+      body: payload,
+      headers: { Authorization: `Bearer ${token}` }
+    }),
+    retry
   );
   return {
     target: "gist",
-    gistId: published.value.id,
-    htmlUrl: published.value.html_url,
-    attempts: published.attempts,
-    files: Object.keys(published.value.files ?? payload.files)
+    gistId: published.id,
+    htmlUrl: published.html_url,
+    files: Object.keys(published.files ?? payload.files)
   };
 }
 export {

package/dist/qa.d.ts

@@ -1,4 +1,4 @@
-import { R as RenderMetadata, D as DesignSpec } from './spec.schema-BxXBTOn-.js';
+import { R as RenderMetadata, D as DesignSpec } from './spec.schema-BUTof436.js';
 import 'zod';
 import '@napi-rs/canvas';
 
@@ -28,7 +28,31 @@ type QaReport = {
     };
     issues: QaIssue[];
 };
+/**
+ * Read and parse a sidecar `.meta.json` file produced by
+ * {@link writeRenderArtifacts}.
+ *
+ * @param path - Absolute or relative path to the `.meta.json` sidecar file.
+ * @returns The parsed {@link RenderMetadata} object.
+ */
 declare function readMetadata(path: string): Promise<RenderMetadata>;
+/**
+ * Run quality-assurance checks on a rendered design image.
+ *
+ * Validates the rendered PNG against the source spec and optional metadata.
+ * Checks include: dimension matching, element clipping against the safe frame,
+ * element overlap detection, WCAG contrast ratio, footer spacing, text
+ * truncation, and draw-command bounds.
+ *
+ * @param options - QA configuration.
+ * @param options.imagePath - Path to the rendered PNG image to validate.
+ * @param options.spec - The {@link DesignSpec} used to produce the image.
+ * @param options.metadata - Optional {@link RenderMetadata} from the render
+ *   pass. When provided, layout-level checks (overlap, clipping, contrast) are
+ *   performed against the element positions recorded in the metadata.
+ * @returns A {@link QaReport} summarising whether the image passes and listing
+ *   any issues found.
+ */
 declare function runQa(options: {
     imagePath: string;
     spec: DesignSpec;

package/dist/qa.js

@@ -62,7 +62,98 @@ import { z as z2 } from "zod";
 
 // src/themes/builtin.ts
 import { z } from "zod";
-var colorHexSchema = z.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "Expected #RRGGBB or #RRGGBBAA color");
+
+// src/utils/color.ts
+function parseChannel(hex, offset) {
+  return Number.parseInt(hex.slice(offset, offset + 2), 16);
+}
+function parseHexColor(hexColor) {
+  const normalized = hexColor.startsWith("#") ? hexColor.slice(1) : hexColor;
+  if (normalized.length !== 6 && normalized.length !== 8) {
+    throw new Error(`Unsupported color format: ${hexColor}`);
+  }
+  return {
+    r: parseChannel(normalized, 0),
+    g: parseChannel(normalized, 2),
+    b: parseChannel(normalized, 4)
+  };
+}
+var rgbaRegex = /^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*([01](?:\.\d+)?|0?\.\d+)\s*)?\)$/;
+var hexColorRegex = /^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function toHex(n) {
+  return n.toString(16).padStart(2, "0");
+}
+function parseRgbaToHex(color) {
+  const match = rgbaRegex.exec(color);
+  if (!match) {
+    throw new Error(`Invalid rgb/rgba color: ${color}`);
+  }
+  const r = Number.parseInt(match[1], 10);
+  const g = Number.parseInt(match[2], 10);
+  const b = Number.parseInt(match[3], 10);
+  if (r > 255 || g > 255 || b > 255) {
+    throw new Error(`RGB channel values must be 0-255, got: ${color}`);
+  }
+  if (match[4] !== void 0) {
+    const a = Number.parseFloat(match[4]);
+    if (a < 0 || a > 1) {
+      throw new Error(`Alpha value must be 0-1, got: ${a}`);
+    }
+    const alphaByte = Math.round(a * 255);
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}${toHex(alphaByte)}`;
+  }
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+function isRgbaColor(color) {
+  return rgbaRegex.test(color);
+}
+function isHexColor(color) {
+  return hexColorRegex.test(color);
+}
+function normalizeColor(color) {
+  if (isHexColor(color)) {
+    return color;
+  }
+  if (isRgbaColor(color)) {
+    return parseRgbaToHex(color);
+  }
+  throw new Error(`Expected #RRGGBB, #RRGGBBAA, rgb(), or rgba() color, got: ${color}`);
+}
+function srgbToLinear(channel) {
+  const normalized = channel / 255;
+  if (normalized <= 0.03928) {
+    return normalized / 12.92;
+  }
+  return ((normalized + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(hexColor) {
+  const normalized = isRgbaColor(hexColor) ? parseRgbaToHex(hexColor) : hexColor;
+  const rgb = parseHexColor(normalized);
+  const r = srgbToLinear(rgb.r);
+  const g = srgbToLinear(rgb.g);
+  const b = srgbToLinear(rgb.b);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrastRatio(foreground, background) {
+  const fg = relativeLuminance(foreground);
+  const bg = relativeLuminance(background);
+  const lighter = Math.max(fg, bg);
+  const darker = Math.min(fg, bg);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// src/themes/builtin.ts
+var colorHexSchema = z.string().refine(
+  (v) => {
+    try {
+      normalizeColor(v);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  { message: "Expected #RRGGBB, #RRGGBBAA, rgb(), or rgba() color" }
+).transform((v) => normalizeColor(v));
 var fontFamilySchema = z.string().min(1).max(120);
 var codeThemeSchema = z.object({
   background: colorHexSchema,
@@ -235,7 +326,17 @@ var builtInThemes = {
 var defaultTheme = builtInThemes.dark;
 
 // src/spec.schema.ts
-var colorHexSchema2 = z2.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "Expected #RRGGBB or #RRGGBBAA color");
+var colorHexSchema2 = z2.string().refine(
+  (v) => {
+    try {
+      normalizeColor(v);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  { message: "Expected #RRGGBB, #RRGGBBAA, rgb(), or rgba() color" }
+).transform((v) => normalizeColor(v));
 var gradientStopSchema = z2.object({
   offset: z2.number().min(0).max(1),
   color: colorHexSchema2
@@ -426,6 +527,9 @@ var flowNodeElementSchema = z2.object({
   label: z2.string().min(1).max(200),
   sublabel: z2.string().min(1).max(300).optional(),
   sublabelColor: colorHexSchema2.optional(),
+  sublabel2: z2.string().min(1).max(300).optional(),
+  sublabel2Color: colorHexSchema2.optional(),
+  sublabel2FontSize: z2.number().min(8).max(32).optional(),
   labelColor: colorHexSchema2.optional(),
   labelFontSize: z2.number().min(10).max(48).optional(),
   color: colorHexSchema2.optional(),
@@ -434,7 +538,12 @@ var flowNodeElementSchema = z2.object({
   cornerRadius: z2.number().min(0).max(64).optional(),
   width: z2.number().int().min(40).max(800).optional(),
   height: z2.number().int().min(30).max(600).optional(),
-  opacity: z2.number().min(0).max(1).default(1)
+  fillOpacity: z2.number().min(0).max(1).default(1),
+  opacity: z2.number().min(0).max(1).default(1),
+  badgeText: z2.string().min(1).max(32).optional(),
+  badgeColor: colorHexSchema2.optional(),
+  badgeBackground: colorHexSchema2.optional(),
+  badgePosition: z2.enum(["top", "inside-top"]).default("inside-top")
 }).strict();
 var connectionElementSchema = z2.object({
   type: z2.literal("connection"),
@@ -523,7 +632,15 @@ var autoLayoutConfigSchema = z2.object({
   nodeSpacing: z2.number().int().min(0).max(512).default(80),
   rankSpacing: z2.number().int().min(0).max(512).default(120),
   edgeRouting: z2.enum(["orthogonal", "polyline", "spline"]).default("polyline"),
-  aspectRatio: z2.number().min(0.5).max(3).optional()
+  aspectRatio: z2.number().min(0.5).max(3).optional(),
+  /** ID of the root node for radial layout. Only relevant when algorithm is 'radial'. */
+  radialRoot: z2.string().min(1).max(120).optional(),
+  /** Fixed radius in pixels for radial layout. Only relevant when algorithm is 'radial'. */
+  radialRadius: z2.number().positive().optional(),
+  /** Compaction strategy for radial layout. Only relevant when algorithm is 'radial'. */
+  radialCompaction: z2.enum(["none", "radial", "wedge"]).optional(),
+  /** Sort strategy for radial layout node ordering. Only relevant when algorithm is 'radial'. */
+  radialSortBy: z2.enum(["id", "connections"]).optional()
 }).strict();
 var gridLayoutConfigSchema = z2.object({
   mode: z2.literal("grid"),
@@ -627,43 +744,6 @@ function parseDesignSpec(input) {
   return designSpecSchema.parse(input);
 }
 
-// src/utils/color.ts
-function parseChannel(hex, offset) {
-  return Number.parseInt(hex.slice(offset, offset + 2), 16);
-}
-function parseHexColor(hexColor) {
-  const normalized = hexColor.startsWith("#") ? hexColor.slice(1) : hexColor;
-  if (normalized.length !== 6 && normalized.length !== 8) {
-    throw new Error(`Unsupported color format: ${hexColor}`);
-  }
-  return {
-    r: parseChannel(normalized, 0),
-    g: parseChannel(normalized, 2),
-    b: parseChannel(normalized, 4)
-  };
-}
-function srgbToLinear(channel) {
-  const normalized = channel / 255;
-  if (normalized <= 0.03928) {
-    return normalized / 12.92;
-  }
-  return ((normalized + 0.055) / 1.055) ** 2.4;
-}
-function relativeLuminance(hexColor) {
-  const rgb = parseHexColor(hexColor);
-  const r = srgbToLinear(rgb.r);
-  const g = srgbToLinear(rgb.g);
-  const b = srgbToLinear(rgb.b);
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-function contrastRatio(foreground, background) {
-  const fg = relativeLuminance(foreground);
-  const bg = relativeLuminance(background);
-  const lighter = Math.max(fg, bg);
-  const darker = Math.min(fg, bg);
-  return (lighter + 0.05) / (darker + 0.05);
-}
-
 // src/qa.ts
 function rectWithin(outer, inner) {
   return inner.x >= outer.x && inner.y >= outer.y && inner.x + inner.width <= outer.x + outer.width && inner.y + inner.height <= outer.y + outer.height;

package/dist/renderer.d.ts

@@ -1,3 +1,3 @@
-export { h as DEFAULT_GENERATOR_VERSION, z as LayoutSnapshot, a as Rect, R as RenderMetadata, J as RenderResult, d as RenderedElement, W as WrittenArtifacts, X as computeSpecHash, a9 as inferSidecarPath, ab as renderDesign, ad as writeRenderArtifacts } from './spec.schema-BxXBTOn-.js';
+export { h as DEFAULT_GENERATOR_VERSION, z as LayoutSnapshot, a as Rect, R as RenderMetadata, J as RenderResult, d as RenderedElement, W as WrittenArtifacts, X as computeSpecHash, a9 as inferSidecarPath, ab as renderDesign, ad as writeRenderArtifacts } from './spec.schema-BUTof436.js';
 import 'zod';
 import '@napi-rs/canvas';