@spectratools/graphic-designer-cli 0.3.1 → 0.3.2

package/dist/cli.js

@@ -10,38 +10,8 @@ import { Cli, z as z3 } from "incur";
 // src/publish/gist.ts
 import { readFile } from "fs/promises";
 import { basename } from "path";
-
-// src/utils/retry.ts
-var DEFAULT_RETRY_POLICY = {
-  maxRetries: 3,
-  baseMs: 500,
-  maxMs: 4e3
-};
-function sleep(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, 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/gist.ts
+import { withRetry } from "@spectratools/cli-shared/middleware";
+import { createHttpClient } from "@spectratools/cli-shared/utils";
 function requireGitHubToken(token) {
   const resolved = token ?? process.env.GITHUB_TOKEN;
   if (!resolved) {
@@ -49,28 +19,21 @@ function requireGitHubToken(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_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"
+  }
+});
 async function publishToGist(options) {
   const token = requireGitHubToken(options.token);
+  const retry = options.retryPolicy ?? DEFAULT_RETRY;
   const [imageBuffer, metadataBuffer] = await Promise.all([
     readFile(options.imagePath),
     readFile(options.metadataPath)
@@ -108,27 +71,27 @@ 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 withRetry(
+    () => github.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)
   };
 }
 
 // src/publish/github.ts
 import { readFile as readFile2 } from "fs/promises";
 import { basename as basename2, posix } from "path";
+import { withRetry as withRetry2 } from "@spectratools/cli-shared/middleware";
+import { HttpError, createHttpClient as createHttpClient2 } from "@spectratools/cli-shared/utils";
 function requireGitHubToken2(token) {
   const resolved = token ?? process.env.GITHUB_TOKEN;
   if (!resolved) {
@@ -136,56 +99,18 @@ function requireGitHubToken2(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_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"
   }
-  return {
-    found: true,
-    value: value.value,
-    attempts
-  };
-}
+});
 function parseRepo(repo) {
   const [owner, name] = repo.split("/");
   if (!owner || !name) {
@@ -201,9 +126,25 @@ function normalizePath(pathPrefix, filename) {
   const trimmed = (pathPrefix ?? "artifacts").replace(/^\/+|\/+$/gu, "");
   return posix.join(trimmed, filename);
 }
+async function githubJsonMaybe(path, token, retry) {
+  return withRetry2(async () => {
+    try {
+      const value = await github2.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 = requireGitHubToken2(options.token);
   const branch = options.branch ?? "main";
+  const retry = options.retryPolicy ?? DEFAULT_RETRY2;
   const commitMessage = options.commitMessage ?? "chore(graphic-designer): publish deterministic artifacts";
   const [imageBuffer, metadataBuffer] = await Promise.all([
     readFile2(options.imagePath),
@@ -221,16 +162,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} (${basename2(upload.sourcePath)})`,
       content: upload.content,
@@ -238,27 +173,24 @@ async function publishToGitHub(options) {
       sha: existing.value?.sha
     };
     const putPath = toApiContentPath(options.repo, upload.destination);
-    const published = await githubJson(
-      putPath,
-      {
+    const published = await withRetry2(
+      () => github2.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
   };
 }
@@ -4814,7 +4746,6 @@ cli.command("publish", {
       issueCount: z3.number()
     }),
     publish: z3.object({
-      attempts: z3.number(),
       summary: z3.string(),
       url: z3.string().optional()
     })
@@ -4867,7 +4798,6 @@ cli.command("publish", {
           issueCount: qa.issues.length
         },
         publish: {
-          attempts: gist.attempts,
           summary: `Published ${gist.files.length} files to gist ${gist.gistId}.`,
           url: gist.htmlUrl
         }
@@ -4880,7 +4810,7 @@ cli.command("publish", {
         retryable: false
       });
     }
-    const github = await publishToGitHub({
+    const github3 = await publishToGitHub({
       imagePath,
       metadataPath,
       repo: c.options.repo,
@@ -4888,7 +4818,7 @@ cli.command("publish", {
       ...c.options.pathPrefix ? { pathPrefix: c.options.pathPrefix } : {},
       ...c.options.description ? { commitMessage: c.options.description } : {}
     });
-    const url = github.files.find((file) => file.htmlUrl)?.htmlUrl;
+    const url = github3.files.find((file) => file.htmlUrl)?.htmlUrl;
     return c.ok({
       target: "github",
       qa: {
@@ -4896,8 +4826,7 @@ cli.command("publish", {
         issueCount: qa.issues.length
       },
       publish: {
-        attempts: github.attempts,
-        summary: `Published ${github.files.length} files to ${github.repo}@${github.branch}.`,
+        summary: `Published ${github3.files.length} files to ${github3.repo}@${github3.branch}.`,
         url
       }
     });

package/dist/index.d.ts

@@ -1,17 +1,42 @@
 import { Cli } from 'incur';
-import { T as ThemeInput, D as DesignSpec, a as Rect, b as DrawCommand, c as Theme, d as RenderedElement } from './spec.schema-BxXBTOn-.js';
-export { A as AutoLayoutConfig, B as BuiltInTheme, C as CardElement, e as CodeBlockElement, f as ConnectionElement, g as ConstraintSpec, h as DEFAULT_GENERATOR_VERSION, i as DEFAULT_RAINBOW_COLORS, j as Decorator, k as DesignSafeFrame, l as DrawBadge, m as DrawBezier, n as DrawCircle, o as DrawFontFamily, p as DrawGradientRect, q as DrawLine, r as DrawPath, s as DrawPoint, t as DrawRect, u as DrawText, E as Element, F as FlowNodeElement, G as Gradient, v as GradientOverlayDecorator, w as GradientSpec, x as GradientStop, y as GridLayoutConfig, I as ImageElement, L as LayoutConfig, z as LayoutSnapshot, M as ManualLayoutConfig, H as RainbowRuleDecorator, R as RenderMetadata, J as RenderResult, S as ShapeElement, K as StackLayoutConfig, N as TerminalElement, O as TextElement, P as ThemeInput, V as VignetteDecorator, W as WrittenArtifacts, Q as builtInThemeBackgrounds, U as builtInThemes, X as computeSpecHash, Y as defaultAutoLayout, Z as defaultCanvas, _ as defaultConstraints, $ as defaultGridLayout, a0 as defaultLayout, a1 as defaultStackLayout, a2 as defaultTheme, a3 as deriveSafeFrame, a4 as designSpecSchema, a5 as drawGradientRect, a6 as drawRainbowRule, a7 as drawVignette, a8 as inferLayout, a9 as inferSidecarPath, aa as parseDesignSpec, ab as renderDesign, ac as resolveTheme, ad as writeRenderArtifacts } from './spec.schema-BxXBTOn-.js';
+import { T as ThemeInput, D as DesignSpec, a as Rect, b as DrawCommand, c as Theme, d as RenderedElement } from './spec.schema-DhAI-tE8.js';
+export { A as AutoLayoutConfig, B as BuiltInTheme, C as CardElement, e as CodeBlockElement, f as ConnectionElement, g as ConstraintSpec, h as DEFAULT_GENERATOR_VERSION, i as DEFAULT_RAINBOW_COLORS, j as Decorator, k as DesignSafeFrame, l as DrawBadge, m as DrawBezier, n as DrawCircle, o as DrawFontFamily, p as DrawGradientRect, q as DrawLine, r as DrawPath, s as DrawPoint, t as DrawRect, u as DrawText, E as Element, F as FlowNodeElement, G as Gradient, v as GradientOverlayDecorator, w as GradientSpec, x as GradientStop, y as GridLayoutConfig, I as ImageElement, L as LayoutConfig, z as LayoutSnapshot, M as ManualLayoutConfig, H as RainbowRuleDecorator, R as RenderMetadata, J as RenderResult, S as ShapeElement, K as StackLayoutConfig, N as TerminalElement, O as TextElement, P as ThemeInput, V as VignetteDecorator, W as WrittenArtifacts, Q as builtInThemeBackgrounds, U as builtInThemes, X as computeSpecHash, Y as defaultAutoLayout, Z as defaultCanvas, _ as defaultConstraints, $ as defaultGridLayout, a0 as defaultLayout, a1 as defaultStackLayout, a2 as defaultTheme, a3 as deriveSafeFrame, a4 as designSpecSchema, a5 as drawGradientRect, a6 as drawRainbowRule, a7 as drawVignette, a8 as inferLayout, a9 as inferSidecarPath, aa as parseDesignSpec, ab as renderDesign, ac as resolveTheme, ad as writeRenderArtifacts } from './spec.schema-DhAI-tE8.js';
 import { SKRSContext2D } from '@napi-rs/canvas';
 export { QaIssue, QaReport, QaSeverity, readMetadata, runQa } from './qa.js';
 import { Highlighter } from 'shiki';
 export { GistPublishOptions, GistPublishResult, GitHubPublishOptions, GitHubPublishResult, publishToGist, publishToGitHub } from './publish/index.js';
 import 'zod';
+import '@spectratools/cli-shared/middleware';
 
 declare const cli: Cli.Cli<{}, undefined, undefined>;
 
 declare const themeToShikiMap: Record<string, string>;
 declare function resolveShikiTheme(theme: ThemeInput): string;
 
+/**
+ * Build a validated {@link DesignSpec} for a flowchart diagram.
+ *
+ * Accepts plain-text node and edge definitions and converts them into
+ * `flow-node` and `connection` elements with automatic ELK-based layout.
+ *
+ * Node tokens use the format `"Label"` or `"Label:shape"` (e.g.
+ * `"Start:pill"`). Edge tokens use `"From->To"` or `"From->To:label"`.
+ *
+ * @param options - Flowchart configuration.
+ * @param options.nodes - Array of node token strings to create.
+ * @param options.edges - Array of edge token strings defining connections.
+ * @param options.title - Optional header title displayed above the flowchart.
+ * @param options.direction - ELK layout direction. Defaults to `"TB"`.
+ * @param options.algorithm - ELK layout algorithm. Defaults to `"layered"`.
+ * @param options.theme - Built-in theme name. Defaults to `"dark"`.
+ * @param options.nodeShape - Default node shape when not specified per-node.
+ *   Defaults to `"rounded-box"`.
+ * @param options.width - Canvas width override in pixels.
+ * @param options.height - Canvas height override in pixels.
+ * @returns A fully validated and parsed {@link DesignSpec}.
+ * @throws When a node token is empty, duplicated, or an edge references an
+ *   unknown node.
+ */
 declare function buildFlowchartSpec(options: {
     nodes: string[];
     edges: string[];
@@ -26,6 +51,31 @@ declare function buildFlowchartSpec(options: {
 
 type WindowControls = 'macos' | 'bw' | 'none';
 
+/**
+ * Build a validated {@link DesignSpec} for a Carbon-style code screenshot.
+ *
+ * Wraps a code snippet in a single `code-block` element with macOS-style window
+ * chrome, drop shadow, and syntax highlighting. The resulting spec uses a
+ * vertical stack layout.
+ *
+ * @param options - Code screenshot configuration.
+ * @param options.code - The source code string to display.
+ * @param options.language - Programming language for syntax highlighting (e.g.
+ *   `"typescript"`).
+ * @param options.title - Optional title shown in the window title bar.
+ * @param options.theme - Built-in theme name. Defaults to `"dark"`.
+ * @param options.showLineNumbers - Whether to render line numbers. Defaults to
+ *   `false`.
+ * @param options.highlightLines - Array of 1-based line numbers to highlight.
+ * @param options.startLine - Starting line number for display. Defaults to `1`.
+ * @param options.width - Canvas width in pixels. Defaults to `800`.
+ * @param options.height - Canvas height in pixels. Defaults to `500`.
+ * @param options.surroundColor - Background colour behind the code window.
+ * @param options.windowControls - Window control style (`"macos"`, `"bw"`, or
+ *   `"none"`). Defaults to `"macos"`.
+ * @param options.scale - Render scale multiplier. Defaults to `2`.
+ * @returns A fully validated and parsed {@link DesignSpec}.
+ */
 declare function buildCodeSpec(options: {
     code: string;
     language: string;
@@ -41,6 +91,31 @@ declare function buildCodeSpec(options: {
     scale?: number;
 }): DesignSpec;
 
+/**
+ * Build a validated {@link DesignSpec} for a terminal screenshot.
+ *
+ * Accepts either raw terminal content or a command/output pair and wraps it in
+ * a single `terminal` element with macOS-style window chrome and a drop shadow.
+ * At least one of `content`, `command`, or `output` must be provided.
+ *
+ * @param options - Terminal screenshot configuration.
+ * @param options.command - Shell command to display (prepended with the prompt).
+ * @param options.output - Command output text.
+ * @param options.content - Raw terminal content — takes precedence over
+ *   `command`/`output` when provided.
+ * @param options.title - Optional window title bar text.
+ * @param options.prompt - Prompt prefix used when rendering `command`. Defaults
+ *   to `"$ "`.
+ * @param options.theme - Built-in theme name. Defaults to `"dark"`.
+ * @param options.width - Canvas width in pixels. Defaults to `800`.
+ * @param options.height - Canvas height in pixels. Defaults to `400`.
+ * @param options.surroundColor - Background colour behind the terminal window.
+ * @param options.windowControls - Window control style (`"macos"`, `"bw"`, or
+ *   `"none"`). Defaults to `"macos"`.
+ * @param options.scale - Render scale multiplier. Defaults to `2`.
+ * @returns A fully validated and parsed {@link DesignSpec}.
+ * @throws When none of `content`, `command`, or `output` is provided.
+ */
 declare function buildTerminalSpec(options: {
     command?: string;
     output?: string;
@@ -55,6 +130,26 @@ declare function buildTerminalSpec(options: {
     scale?: number;
 }): DesignSpec;
 
+/**
+ * Build a validated {@link DesignSpec} for a card grid layout.
+ *
+ * Converts an array of card data into `card` elements arranged in a grid. The
+ * number of columns is inferred from the card count when not specified
+ * explicitly.
+ *
+ * @param options - Card grid configuration.
+ * @param options.cards - Array of card data objects. Each must include `title`
+ *   and `body`; `badge`, `metric`, and `tone` are optional.
+ * @param options.title - Optional header title displayed above the card grid.
+ * @param options.subtitle - Optional header subtitle (only rendered when
+ *   `title` is also set).
+ * @param options.columns - Number of grid columns. When omitted, a heuristic
+ *   chooses based on card count (1–4 columns).
+ * @param options.theme - Built-in theme name. Defaults to `"dark"`.
+ * @param options.width - Canvas width override in pixels.
+ * @param options.height - Canvas height override in pixels.
+ * @returns A fully validated and parsed {@link DesignSpec}.
+ */
 declare function buildCardsSpec(options: {
     cards: Array<{
         title: string;
@@ -88,10 +183,46 @@ type ElkLayoutResult = LayoutResult & {
     edgeRoutes?: Map<string, EdgeRoute>;
 };
 
+/**
+ * Render an array of freestyle draw commands onto a canvas context.
+ *
+ * Supports eight command types: `rect`, `circle`, `text`, `line`, `bezier`,
+ * `path`, `badge`, and `gradient-rect`. Each command is rendered in order and
+ * produces a corresponding {@link RenderedElement} with computed bounds for
+ * downstream QA checks.
+ *
+ * @param ctx - The `@napi-rs/canvas` 2D rendering context to draw into.
+ * @param commands - Array of {@link DrawCommand} objects from the design spec's
+ *   `draw` field.
+ * @param theme - The resolved {@link Theme} used for font resolution and
+ *   default colours.
+ * @returns An array of {@link RenderedElement} entries describing each drawn
+ *   command's bounding box and colours.
+ */
 declare function renderDrawCommands(ctx: SKRSContext2D, commands: DrawCommand[], theme: Theme): RenderedElement[];
 
+/**
+ * Register the bundled font families (Inter, JetBrains Mono, Space Grotesk)
+ * with the global `@napi-rs/canvas` font registry.
+ *
+ * **Must be called before {@link renderDesign}.** Without registered fonts the
+ * canvas will fall back to system defaults, producing inconsistent output across
+ * environments. {@link renderDesign} calls this internally, but consumers using
+ * lower-level APIs (e.g. `renderDrawCommands`) should call it explicitly.
+ *
+ * This function is idempotent — subsequent calls after the first are no-ops.
+ */
 declare function loadFonts(): void;
 
+/**
+ * Initialise (or return the existing) shiki syntax highlighter singleton.
+ *
+ * Loads all bundled themes and languages on first call. Subsequent calls return
+ * the cached instance immediately. Must be called (or allowed to be called
+ * implicitly via {@link highlightCode}) before any syntax highlighting work.
+ *
+ * @returns The shared shiki {@link Highlighter} instance.
+ */
 declare function initHighlighter(): Promise<Highlighter>;
 type HighlightedLine = {
     tokens: Array<{
@@ -99,7 +230,30 @@ type HighlightedLine = {
         color: string;
     }>;
 };
+/**
+ * Tokenise and syntax-highlight a code string.
+ *
+ * Lazily initialises the highlighter via {@link initHighlighter} if it has not
+ * been created yet. Language aliases (e.g. `"ts"` → `"typescript"`) are
+ * resolved automatically.
+ *
+ * @param code - The source code string to highlight.
+ * @param language - Programming language identifier or alias (e.g.
+ *   `"typescript"`, `"ts"`, `"python"`).
+ * @param themeName - Shiki theme name to use for colouring (e.g.
+ *   `"github-dark"`).
+ * @returns An array of {@link HighlightedLine} objects, one per line, each
+ *   containing an array of coloured text tokens.
+ * @throws When the language or theme is not among the bundled set.
+ */
 declare function highlightCode(code: string, language: string, themeName: string): Promise<HighlightedLine[]>;
+/**
+ * Dispose the shared shiki highlighter instance and release its resources.
+ *
+ * After disposal, the next call to {@link initHighlighter} or
+ * {@link highlightCode} will create a fresh instance. Safe to call even when no
+ * highlighter has been initialised (no-op in that case).
+ */
 declare function disposeHighlighter(): void;
 
 export { DesignSpec, DrawCommand, type EdgeRoute, type ElkLayoutResult, type HighlightedLine, type LayoutResult, Rect, RenderedElement, Theme, buildCardsSpec, buildCodeSpec, buildFlowchartSpec, buildTerminalSpec, cli, disposeHighlighter, highlightCode, initHighlighter, loadFonts, renderDrawCommands, resolveShikiTheme, themeToShikiMap };