@spectratools/graphic-designer-cli 0.3.1

package/dist/publish/index.d.ts

@@ -0,0 +1,49 @@
+interface RetryPolicy {
+    maxRetries: number;
+    baseMs: number;
+    maxMs: number;
+}
+
+type GitHubPublishOptions = {
+    imagePath: string;
+    metadataPath: string;
+    repo: string;
+    pathPrefix?: string;
+    branch?: string;
+    token?: string;
+    commitMessage?: string;
+    retryPolicy?: RetryPolicy;
+};
+type GitHubPublishResult = {
+    target: 'github';
+    repo: string;
+    branch: string;
+    attempts: number;
+    files: Array<{
+        path: string;
+        htmlUrl?: string;
+        sha?: string;
+    }>;
+};
+declare function publishToGitHub(options: GitHubPublishOptions): Promise<GitHubPublishResult>;
+
+type GistPublishOptions = {
+    imagePath: string;
+    metadataPath: string;
+    gistId?: string;
+    description?: string;
+    filenamePrefix?: string;
+    public?: boolean;
+    token?: string;
+    retryPolicy?: RetryPolicy;
+};
+type GistPublishResult = {
+    target: 'gist';
+    gistId: string;
+    htmlUrl: string;
+    attempts: number;
+    files: string[];
+};
+declare function publishToGist(options: GistPublishOptions): Promise<GistPublishResult>;
+
+export { type GistPublishOptions, type GistPublishResult, type GitHubPublishOptions, type GitHubPublishResult, publishToGist, publishToGitHub };

package/dist/publish/index.js

@@ -0,0 +1,259 @@
+// 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
+function requireGitHubToken(token) {
+  const resolved = token ?? process.env.GITHUB_TOKEN;
+  if (!resolved) {
+    throw new Error("GITHUB_TOKEN is required for GitHub publish adapter.");
+  }
+  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 };
+  }
+  return {
+    found: true,
+    value: value.value,
+    attempts
+  };
+}
+function parseRepo(repo) {
+  const [owner, name] = repo.split("/");
+  if (!owner || !name) {
+    throw new Error(`Invalid repo "${repo}". Expected owner/name.`);
+  }
+  return { owner, name };
+}
+function toApiContentPath(repo, filePath) {
+  const { owner, name } = parseRepo(repo);
+  return `/repos/${owner}/${name}/contents/${filePath}`;
+}
+function normalizePath(pathPrefix, filename) {
+  const trimmed = (pathPrefix ?? "artifacts").replace(/^\/+|\/+$/gu, "");
+  return posix.join(trimmed, filename);
+}
+async function publishToGitHub(options) {
+  const token = requireGitHubToken(options.token);
+  const branch = options.branch ?? "main";
+  const commitMessage = options.commitMessage ?? "chore(graphic-designer): publish deterministic artifacts";
+  const [imageBuffer, metadataBuffer] = await Promise.all([
+    readFile(options.imagePath),
+    readFile(options.metadataPath)
+  ]);
+  const uploads = [
+    {
+      sourcePath: options.imagePath,
+      destination: normalizePath(options.pathPrefix, basename(options.imagePath)),
+      content: imageBuffer.toString("base64")
+    },
+    {
+      sourcePath: options.metadataPath,
+      destination: normalizePath(options.pathPrefix, basename(options.metadataPath)),
+      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 body = {
+      message: `${commitMessage} (${basename(upload.sourcePath)})`,
+      content: upload.content,
+      branch,
+      sha: existing.value?.sha
+    };
+    const putPath = toApiContentPath(options.repo, upload.destination);
+    const published = await githubJson(
+      putPath,
+      {
+        method: "PUT",
+        body: JSON.stringify(body)
+      },
+      token,
+      options.retryPolicy
+    );
+    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 } : {}
+    });
+  }
+  return {
+    target: "github",
+    repo: options.repo,
+    branch,
+    attempts: totalAttempts,
+    files
+  };
+}
+
+// src/publish/gist.ts
+import { readFile as readFile2 } from "fs/promises";
+import { basename as basename2 } from "path";
+function requireGitHubToken2(token) {
+  const resolved = token ?? process.env.GITHUB_TOKEN;
+  if (!resolved) {
+    throw new Error("GITHUB_TOKEN is required for gist publish adapter.");
+  }
+  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);
+}
+async function publishToGist(options) {
+  const token = requireGitHubToken2(options.token);
+  const [imageBuffer, metadataBuffer] = await Promise.all([
+    readFile2(options.imagePath),
+    readFile2(options.metadataPath)
+  ]);
+  const prefix = options.filenamePrefix ?? basename2(options.imagePath, ".png");
+  const imageBase64 = imageBuffer.toString("base64");
+  const metadataText = metadataBuffer.toString("utf8");
+  const readmeName = `${prefix}.md`;
+  const b64Name = `${prefix}.png.base64.txt`;
+  const metadataName = `${prefix}.meta.json`;
+  const markdown = [
+    `# ${prefix}`,
+    "",
+    "Deterministic graphic-designer artifact.",
+    "",
+    `- Source image filename: ${basename2(options.imagePath)}`,
+    `- Sidecar metadata filename: ${metadataName}`,
+    "",
+    "## Preview",
+    "",
+    `![${prefix}](data:image/png;base64,${imageBase64})`,
+    "",
+    "## Notes",
+    "",
+    `- This gist stores the PNG as base64 in \`${b64Name}\` for deterministic transport.`
+  ].join("\n");
+  const payload = {
+    description: options.description ?? "graphic-designer publish",
+    public: options.public ?? false,
+    files: {
+      [readmeName]: { content: markdown },
+      [b64Name]: { content: imageBase64 },
+      [metadataName]: { content: metadataText }
+    }
+  };
+  const endpoint = options.gistId ? `/gists/${options.gistId}` : "/gists";
+  const method = options.gistId ? "PATCH" : "POST";
+  const published = await gistJson(
+    endpoint,
+    {
+      method,
+      body: JSON.stringify(payload)
+    },
+    token,
+    options.retryPolicy
+  );
+  return {
+    target: "gist",
+    gistId: published.value.id,
+    htmlUrl: published.value.html_url,
+    attempts: published.attempts,
+    files: Object.keys(published.value.files ?? payload.files)
+  };
+}
+export {
+  publishToGist,
+  publishToGitHub
+};

package/dist/qa.d.ts

@@ -0,0 +1,38 @@
+import { R as RenderMetadata, D as DesignSpec } from './spec.schema-BxXBTOn-.js';
+import 'zod';
+import '@napi-rs/canvas';
+
+type QaSeverity = 'error' | 'warning';
+type QaIssue = {
+    code: 'DIMENSIONS_MISMATCH' | 'ELEMENT_CLIPPED' | 'ELEMENT_OVERLAP' | 'LOW_CONTRAST' | 'FOOTER_SPACING' | 'TEXT_TRUNCATED' | 'MISSING_LAYOUT' | 'DRAW_OUT_OF_BOUNDS';
+    severity: QaSeverity;
+    message: string;
+    elementId?: string;
+    details?: Record<string, number | string | boolean>;
+};
+type QaReport = {
+    pass: boolean;
+    checkedAt: string;
+    imagePath: string;
+    expected: {
+        width: number;
+        height: number;
+        scale: number;
+        minContrastRatio: number;
+        minFooterSpacing: number;
+    };
+    measured: {
+        width?: number;
+        height?: number;
+        footerSpacingPx?: number;
+    };
+    issues: QaIssue[];
+};
+declare function readMetadata(path: string): Promise<RenderMetadata>;
+declare function runQa(options: {
+    imagePath: string;
+    spec: DesignSpec;
+    metadata?: RenderMetadata;
+}): Promise<QaReport>;
+
+export { type QaIssue, type QaReport, type QaSeverity, readMetadata, runQa };