@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/tools/visual-url/css-sample.mjs

@@ -0,0 +1,109 @@
+export const samplingMethod = "root-theme-font-component-priority-v1";
+
+export function declarationPriority(item) {
+  if (
+    /@font-face/i.test(item.selector) ||
+    /(?:^|-)font(?:-|$)|typography|line-height|letter-spacing/.test(item.property)
+  )
+    return 3;
+  if (/(?:^|[\s,])(?::root|html)(?:$|[\s,[.:#])|theme|\bdark\b|\blight\b/i.test(item.selector))
+    return 4;
+  if (/^--/.test(item.property)) return 4;
+  if (
+    /button|card|input|select|textarea|nav|dialog|modal|badge|heading|\bh[1-6]\b/i.test(
+      item.selector,
+    )
+  )
+    return 2;
+  if (
+    /color|background|padding|margin|gap|radius|border|shadow|display|width|height|align|justify/.test(
+      item.property,
+    )
+  )
+    return 1;
+  return 0;
+}
+
+export function declarationSampler(maximum) {
+  const buckets = Array.from({ length: 5 }, () => new Map());
+  const counts = Array(5).fill(0);
+  let total = 0;
+  let oversized = 0;
+  return {
+    add(item) {
+      total++;
+      if (!item) {
+        oversized++;
+        return;
+      }
+      const priority = declarationPriority(item);
+      const bucket = buckets[priority];
+      const key = `${item.source_hash}:${item.selector}`;
+      if (!bucket.has(key)) {
+        if (bucket.size >= maximum) {
+          const removed = bucket.keys().next().value;
+          counts[priority] -= bucket.get(removed).length;
+          bucket.delete(removed);
+        }
+        bucket.set(key, []);
+      }
+      const group = bucket.get(key);
+      if (group.length >= maximum) return;
+      group.push({ item, sequence: total });
+      counts[priority]++;
+      if (counts[priority] > maximum * 4) {
+        const largest = [...bucket.values()].reduce((a, b) => (a.length >= b.length ? a : b));
+        largest.pop();
+        counts[priority]--;
+      }
+    },
+    finish() {
+      // Reserve bounded representation across categories; root floods cannot erase fonts/components.
+      const quotas = [5, 10, 15, 20, 50].map((weight) => Math.floor((maximum * weight) / 100));
+      const ordered = buckets.map((bucket) => {
+        const sources = new Map();
+        for (const rows of bucket.values()) {
+          const key = rows[0]?.item.source_hash;
+          if (!sources.has(key)) sources.set(key, []);
+          sources.get(key).push([...rows]);
+        }
+        const result = [];
+        while (
+          result.length < maximum &&
+          [...sources.values()].some((groups) => groups.some((rows) => rows.length))
+        ) {
+          for (const groups of sources.values()) {
+            const rows = groups.shift();
+            if (rows?.length) result.push(rows.shift());
+            if (rows?.length) groups.push(rows);
+            if (result.length === maximum) break;
+          }
+        }
+        return result;
+      });
+      const selected = ordered.flatMap((bucket, index) => bucket.slice(0, quotas[index]));
+      for (let index = ordered.length - 1; index >= 0 && selected.length < maximum; index--) {
+        selected.push(
+          ...ordered[index].slice(quotas[index], quotas[index] + maximum - selected.length),
+        );
+      }
+      selected.sort((a, b) => a.sequence - b.sequence);
+      return {
+        declarations: selected.map((row) => row.item),
+        sampling: {
+          method: samplingMethod,
+          total,
+          sampled: selected.length,
+          truncated: total - selected.length,
+          oversized,
+        },
+      };
+    },
+  };
+}
+
+export function selectDeclarations(values, maximum) {
+  const sampler = declarationSampler(maximum);
+  for (const item of values) sampler.add(item);
+  return sampler.finish().declarations;
+}

package/templates/.agents/tools/visual-url/design-lint.mjs

@@ -0,0 +1,83 @@
+import { safeVisualValue } from "./visual-model.mjs";
+
+export const designLintMethod = "visual-token-lint-v1";
+const rules = [
+  { id: "token-value", description: "Valores compatíveis com o contrato de tokens do Maker." },
+  {
+    id: "token-evidence",
+    description: "Tokens ligados a observações existentes, sem falha registrada.",
+  },
+  { id: "token-provenance", description: "Proveniência registrada para cada token." },
+  {
+    id: "semantic-colors",
+    description: "Fundo, texto, cor primária e texto primário disponíveis.",
+  },
+  { id: "body-family", description: "Família tipográfica principal disponível." },
+  { id: "scales", description: "Escalas de espaçamento e raio disponíveis." },
+];
+
+// Lint the extracted design contract, not the remote site's source or Google DESIGN.md syntax.
+export function lintDesign(proposal, model) {
+  const rows = [];
+  for (const group of ["colors", "typography", "spacing", "radii", "borders", "shadows"])
+    for (const [key, token] of Object.entries(model?.tokens?.[group] ?? {}))
+      if (token != null) rows.push({ path: `tokens.${group}.${key}`, token });
+  for (const [index, component] of (model?.components ?? []).entries())
+    for (const [key, token] of Object.entries(component.tokens ?? {}))
+      if (token != null) rows.push({ path: `components.${index}.${key}`, token });
+  if (!rows.length) return null;
+  const observations = new Map((proposal?.observations ?? []).map((item) => [item.id, item]));
+  const findings = [];
+  const add = (rule, severity, path, message) => findings.push({ rule, severity, path, message });
+  for (const { path, token } of rows) {
+    if (typeof token.property !== "string" || safeVisualValue(token.property, token.value) == null)
+      add("token-value", "error", path, "Valor inválido ou não suportado pelo contrato visual.");
+    if (
+      !Array.isArray(token.evidence) ||
+      !token.evidence.length ||
+      token.evidence.some((id) => !observations.has(id) || observations.get(id).reason != null)
+    )
+      add(
+        "token-evidence",
+        "error",
+        path,
+        "Token sem vínculo válido com as observações da extração.",
+      );
+    if (!token.provenance || typeof token.provenance !== "object" || !token.provenance.method)
+      add("token-provenance", "error", path, "Token sem método de proveniência registrado.");
+  }
+  for (const role of ["background", "foreground", "primary", "primary_foreground"])
+    if (!model.tokens.colors?.[role])
+      add(
+        "semantic-colors",
+        "warning",
+        `tokens.colors.${role}`,
+        "Papel semântico ausente; o preview depende de fallback.",
+      );
+  if (!model.tokens.typography?.body_family)
+    add(
+      "body-family",
+      "warning",
+      "tokens.typography.body_family",
+      "Família principal ausente; o preview depende de fallback.",
+    );
+  for (const scale of ["spacing", "radii"])
+    if (!model.tokens[scale]?.length)
+      add("scales", "warning", `tokens.${scale}`, "Escala não disponível no modelo extraído.");
+  const errors = findings.filter((item) => item.severity === "error").length;
+  const warnings = findings.filter((item) => item.severity === "warning").length;
+  return {
+    method: designLintMethod,
+    status: "evaluated",
+    scope:
+      "Lint local do modelo de design extraído. Não executa o lint do site nem o @google/design.md.",
+    checked_tokens: rows.length,
+    errors,
+    warnings,
+    score: Math.max(0, 100 - errors * 20 - warnings * 5),
+    formula: "100 − 20 por erro − 5 por aviso, com mínimo 0.",
+    rules,
+    findings: findings.slice(0, 100),
+    omitted_findings: Math.max(0, findings.length - 100),
+  };
+}

package/templates/.agents/tools/visual-url/design-score.mjs

@@ -0,0 +1,217 @@
+import { semanticContrast } from "./contrast.mjs";
+
+export { contrastRatio } from "./contrast.mjs";
+
+import { lintDesign } from "./design-lint.mjs";
+import { generatedTokens } from "./generated-tokens.mjs";
+
+export const designScoreMethod = "design-score-v3";
+export function designGrade(score) {
+  return !Number.isFinite(score)
+    ? null
+    : score >= 90
+      ? "A"
+      : score >= 80
+        ? "B"
+        : score >= 70
+          ? "C"
+          : score >= 60
+            ? "D"
+            : "F";
+}
+const unique = (values) => [...new Set(values)];
+const dimension = (value) => /^(?:0|(?:\d*\.)?\d+(?:px|rem|em|%))$/.test(value);
+function category(id, label, score, value, ideal, explanation, evidence = []) {
+  const rounded = Number.isFinite(score) ? Math.round(score) : null;
+  return {
+    id,
+    label,
+    score: rounded,
+    grade: designGrade(rounded),
+    status: rounded == null ? "unavailable" : "evaluated",
+    value,
+    ideal,
+    explanation,
+    evidence: unique(evidence).slice(0, 16),
+  };
+}
+
+// A presentation projection: never replaces the immutable extraction coverage report.
+export function designScore(proposal, report, model) {
+  if (!proposal || report?.status !== "measured-evidence" || proposal.status === "failed")
+    return null;
+  const declarations = (proposal.observations ?? [])
+    .filter(
+      (item) =>
+        item.reason == null &&
+        ["static-css-declaration", "browser-CSS"].includes(item.provenance?.method),
+    )
+    .map((item) => {
+      const separator = String(item.value).indexOf(":");
+      return {
+        id: item.id,
+        property: String(item.value).slice(0, separator).trim().toLowerCase(),
+        value: String(item.value)
+          .slice(separator + 1)
+          .trim(),
+      };
+    });
+  const evidence = (rows) => rows.flatMap((row) => row.evidence ?? [row.id]).filter(Boolean);
+  const colors = unique((report.colors ?? []).map((row) => row.value));
+  const typography = report.typography ?? [];
+  const families = unique(
+    typography
+      .filter(
+        (row) =>
+          /font-family$/.test(row.property) && !/^(inherit|initial|unset|var\()/i.test(row.value),
+      )
+      .map((row) => row.value.split(",")[0].trim().replace(/["']/g, "").toLowerCase()),
+  );
+  const sizes = unique(
+    typography
+      .filter((row) => /font-size$/.test(row.property) && dimension(row.value))
+      .map((row) => row.value),
+  );
+  const levels = (rows) => unique(rows.flatMap((row) => row.value.split(/\s+/)).filter(dimension));
+  const spacing = levels(report.spacing ?? []),
+    radii = levels(report.radii ?? []);
+  const styled = declarations.filter(
+    (row) =>
+      !row.property.startsWith("--") &&
+      /^(?:color|background(?:-color)?|border(?:-.+)?|font(?:-.+)?|line-height|letter-spacing|padding(?:-.+)?|margin(?:-.+)?|gap|(?:row|column)-gap|box-shadow|fill|stroke)$/.test(
+        row.property,
+      ),
+  );
+  const references = styled.filter((row) => /var\(\s*--[\w-]+/.test(row.value));
+  const tokenPercent = styled.length ? (100 * references.length) / styled.length : null;
+  const colorScore = !colors.length
+    ? null
+    : colors.length > 80
+      ? 50
+      : colors.length > 60
+        ? 70
+        : colors.length > 40
+          ? 85
+          : colors.length > 25
+            ? 95
+            : 100;
+  let typeScore = !families.length
+    ? null
+    : families.length > 6
+      ? 50
+      : families.length > 4
+        ? 75
+        : families.length === 1
+          ? 85
+          : 100;
+  if (typeScore != null && sizes.length < 4) typeScore = Math.min(typeScore, 70);
+  const scaleScore = (count, min, max) =>
+    count === 0 ? null : count > max ? 75 : count >= min ? 100 : count >= min - 1 ? 80 : 60;
+  const pairs = semanticContrast(model);
+  const passing = pairs.filter((pair) => pair.ratio >= 4.5).length;
+  const lint = lintDesign(proposal, model);
+  const categories = [
+    category(
+      "color_discipline",
+      "Color Discipline",
+      colorScore,
+      `${colors.length} cores`,
+      "Até 40 cores",
+      "Paleta CSS disponível: até 25 = 100; 26–40 = 95; 41–60 = 85; 61–80 = 70; acima = 50. Pode incluir temas e estados não visíveis na captura.",
+      evidence(report.colors ?? []),
+    ),
+    category(
+      "typography",
+      "Typography",
+      typeScore,
+      `${families.length} famílias · ${sizes.length} tamanhos`,
+      "2–4 famílias; ≥4 tamanhos",
+      "Primeira família de cada declaração, sem contar fallbacks: 1 = 85; 2–4 = 100; 5–6 = 75; acima = 50. Menos de 4 tamanhos limita a 70.",
+      evidence(typography),
+    ),
+    category(
+      "spacing_system",
+      "Spacing System",
+      scaleScore(spacing.length, 4, 8),
+      `${spacing.length} medidas`,
+      "4–8 medidas",
+      "Valores escalares únicos de margem, padding e gap. 4–8 = 100; 3 = 80; 1–2 = 60; acima de 8 = 75. Expressões não resolvidas são excluídas.",
+      evidence(report.spacing ?? []),
+    ),
+    category(
+      "border_radii",
+      "Border Radii",
+      scaleScore(radii.length, 3, 6),
+      `${radii.length} níveis`,
+      "3–6 níveis",
+      "Raios escalares únicos: 3–6 = 100; 2 = 80; 1 = 60; acima de 6 = 75.",
+      evidence(report.radii ?? []),
+    ),
+    category(
+      "tokenization",
+      "Tokenização da origem",
+      tokenPercent,
+      `${references.length}/${styled.length} declarações usam var()`,
+      "≥80%",
+      "100 × declarações visuais com var() / declarações visuais coletadas. Exclui definições --token e estilos computados; mantém valores literais e constantes no denominador para não elevar a nota por exclusão seletiva. CSS compilado e amostragem limitam a interpretação. Não mede a qualidade do DESIGN.md gerado.",
+      evidence(references),
+    ),
+    category(
+      "lint_compliance",
+      "Lint Compliance",
+      lint?.score ?? null,
+      lint
+        ? `${lint.errors} erros · ${lint.warnings} avisos · ${lint.checked_tokens} tokens verificados`
+        : "Modelo visual indisponível",
+      "0 erros · 0 avisos",
+      lint
+        ? `${lint.scope} ${lint.formula}`
+        : "Sem tokens para executar o lint; categoria excluída da média.",
+    ),
+    category(
+      "accessibility",
+      "Accessibility",
+      pairs.length ? (passing / pairs.length) * 100 : null,
+      pairs.length
+        ? `${passing}/${pairs.length} pares ≥4,5:1`
+        : "Sem pares de texto/fundo com suporte",
+      "100% dos pares ≥4,5:1",
+      pairs.length
+        ? "Contraste dos pares semânticos disponíveis, para texto normal. Não é auditoria completa de acessibilidade nem avaliação de todos os elementos da página."
+        : "Nenhum par opaco de texto/fundo foi estabelecido nesta coleta. Reprocesse com navegador para obter estilos calculados; gradientes, imagens e transparências sem fundo conhecido permanecem não avaliados. Ausência de evidência não recebe nota.",
+      evidence(pairs),
+    ),
+  ];
+  const evaluated = categories.filter((item) => item.score != null);
+  const overall = evaluated.length
+    ? Math.round(evaluated.reduce((sum, item) => sum + item.score, 0) / evaluated.length)
+    : null;
+  return {
+    method: designScoreMethod,
+    overall,
+    grade: designGrade(overall),
+    categories,
+    generated_token_quality: generatedTokens(proposal, model).quality,
+    lint,
+    contrast_pairs: pairs,
+    evaluated_categories: evaluated.length,
+    total_categories: categories.length,
+    formula:
+      "Média aritmética das categorias avaliadas, com pesos iguais. A ≥90; B ≥80; C ≥70; D ≥60; F <60. Não avaliadas ficam fora da média.",
+    scope:
+      "Heurística do sistema visual extraído; não representa avaliação estética ou certificação de acessibilidade.",
+    limitations: [
+      ...(report.sampling?.truncated > 0
+        ? ["CSS amostrado: o resultado pode mudar com uma coleta mais ampla."]
+        : []),
+      ...([report.colors, typography, report.spacing, report.radii].some(
+        (rows) => rows?.length >= 64,
+      )
+        ? [
+            "Uma ou mais listas atingiram o limite de 64 valores do relatório; contagens são limitadas ao conjunto disponível.",
+          ]
+        : []),
+      "Medidas em unidades diferentes são contadas separadamente. Lint avalia o contrato visual local; notas não são diretamente comparáveis ao método antigo.",
+    ],
+  };
+}

package/templates/.agents/tools/visual-url/failure.mjs

@@ -0,0 +1,56 @@
+import { displayUrl, safeText, timestamp } from "./policy.mjs";
+
+export function httpFailure(status, source, challenge = false) {
+  const message = challenge
+    ? "Coleta bloqueada por desafio de acesso; o coletor não contorna essa proteção"
+    : `Fonte respondeu HTTP ${status}; coleta não concluída`;
+  return Object.assign(new Error(message), {
+    failure: {
+      kind: challenge ? "access-challenge" : "http-error",
+      http_status: status,
+      source_url: displayUrl(source),
+      observed_at: new Date().toISOString(),
+      stage: "fetch-html",
+      retry: "explicit",
+      message,
+    },
+  });
+}
+export function failureRecord(error, source, stage = "fetch-html") {
+  if (error?.failure) return validateFailure({ ...error.failure, stage });
+  const code =
+    typeof error?.code === "string" && /^[A-Z_0-9]{1,32}$/.test(error.code) ? error.code : null;
+  return validateFailure({
+    kind: error?.name === "AbortError" ? "cancelled" : "extraction-error",
+    http_status: null,
+    source_url: displayUrl(source),
+    observed_at: new Date().toISOString(),
+    stage,
+    retry: "explicit",
+    message: safeText(
+      code ? `I/O ${code}` : String(error?.message ?? "Falha de coleta").slice(0, 512),
+      512,
+    ),
+  });
+}
+export function validateFailure(value) {
+  const keys = ["kind", "http_status", "source_url", "observed_at", "stage", "retry", "message"];
+  if (
+    !value ||
+    Object.keys(value).sort().join() !== keys.sort().join() ||
+    !["access-challenge", "http-error", "extraction-error", "interrupted", "cancelled"].includes(
+      value.kind,
+    ) ||
+    (value.http_status !== null &&
+      (!Number.isInteger(value.http_status) ||
+        value.http_status < 100 ||
+        value.http_status > 599)) ||
+    value.source_url !== displayUrl(value.source_url) ||
+    value.retry !== "explicit" ||
+    !/^[a-z-]{1,32}$/.test(value.stage) ||
+    safeText(value.message, 512) !== value.message
+  )
+    throw new Error("Invalid structured extraction failure");
+  timestamp(value.observed_at);
+  return value;
+}

package/templates/.agents/tools/visual-url/files.mjs

@@ -0,0 +1,176 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { evidenceLimits } from "./policy.mjs";
+import { hash } from "./transport.mjs";
+
+export function id(value) {
+  if (
+    typeof value !== "string" ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(value) ||
+    /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(value)
+  )
+    throw new Error("Invalid extraction ID");
+  return value;
+}
+function local(value) {
+  if (
+    typeof value !== "string" ||
+    !value ||
+    value.length > 220 ||
+    isAbsolute(value) ||
+    /[\\:<>"|?*]/.test(value) ||
+    [...value].some((char) => char.charCodeAt(0) < 32) ||
+    value
+      .split("/")
+      .some(
+        (part) =>
+          !part ||
+          part === "." ||
+          part === ".." ||
+          /[. ]$/.test(part) ||
+          /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part),
+      )
+  )
+    throw new Error("Unsafe local artifact path");
+  return value;
+}
+export async function path(root, value, create = false) {
+  let current = root;
+  const parts = local(value).split("/");
+  for (const [index, part] of parts.entries()) {
+    current = resolve(current, part);
+    let stat = await lstat(current).catch((error) => {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    });
+    if (!stat && create && index < parts.length - 1) {
+      await mkdir(current).catch((error) => {
+        if (error.code !== "EEXIST") throw error;
+      });
+      stat = await lstat(current);
+    }
+    if (
+      stat?.isSymbolicLink() ||
+      (stat && index < parts.length - 1 && !stat.isDirectory()) ||
+      (stat && index === parts.length - 1 && !stat.isFile())
+    )
+      throw new Error("Artifact path has symlink/reparse or wrong type");
+  }
+  return current;
+}
+export async function read(root, value, maximum = 1048576) {
+  const file = await path(root, value);
+  const handle = await open(file, "r");
+  try {
+    const stat = await handle.stat();
+    const actual = await realpath(file);
+    const offset = relative(root, actual);
+    if (!stat.isFile() || stat.size > maximum || offset.startsWith("..") || isAbsolute(offset))
+      throw new Error("Artifact read boundary/size violation");
+    const bytes = await handle.readFile();
+    if (bytes.length > maximum) throw new Error("Artifact size exceeded");
+    return bytes;
+  } finally {
+    await handle.close();
+  }
+}
+export async function write(root, value, bytes) {
+  const file = await path(root, value, true);
+  const handle = await open(file, "wx", 0o600);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+export async function publish(root, extractionId, files) {
+  id(extractionId);
+  // Reject the whole payload before creating output directories, files or receipts.
+  for (const [name, content] of Object.entries(files))
+    if (
+      !Buffer.isBuffer(content) ||
+      content.length >
+        (name === "screenshot.png"
+          ? evidenceLimits.screenshot_bytes
+          : evidenceLimits.text_artifact_bytes)
+    )
+      throw new Error("Extraction artifact payload exceeds bounded capacity");
+  const marker = await path(root, ".agents/private/state/visual-url/.gitignore", true);
+  const handle = await open(marker, "wx", 0o600).catch((error) => {
+    if (error.code === "EEXIST") return null;
+    throw error;
+  });
+  if (handle) {
+    try {
+      await handle.writeFile("*\n!.gitignore\n");
+    } finally {
+      await handle.close();
+    }
+  }
+  const destination = await path(
+    root,
+    `.agents/private/state/visual-url/${extractionId}/receipt.json`,
+    true,
+  );
+  const directory = dirname(destination);
+  const lock = await open(resolve(directory, "_publish.lock"), "wx", 0o600);
+  try {
+    const receiptPath = await path(
+      root,
+      `.agents/private/state/visual-url/${extractionId}/receipt.json`,
+    );
+    if (
+      await lstat(receiptPath).catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      })
+    )
+      throw new Error("Extraction ID already committed; choose a new revision ID");
+    const inventory = [];
+    for (const [name, bytes] of Object.entries(files)) {
+      const target = await path(root, `.agents/private/state/visual-url/${extractionId}/${name}`);
+      if (
+        await lstat(target).catch((error) => {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        })
+      )
+        throw new Error(
+          "Uncommitted extraction material preserved; choose new ID or bounded repair",
+        );
+      const stage = `.agents/private/state/visual-url/${extractionId}/_stage-${randomUUID()}`;
+      await write(root, stage, bytes);
+      await rename(await path(root, stage), target);
+      if (
+        !(
+          await read(
+            root,
+            `.agents/private/state/visual-url/${extractionId}/${name}`,
+            name === "screenshot.png"
+              ? evidenceLimits.screenshot_bytes
+              : evidenceLimits.text_artifact_bytes,
+          )
+        ).equals(bytes)
+      )
+        throw new Error("Extraction write verification failed");
+      inventory.push({ path: name, bytes: bytes.length, hash: hash(bytes) });
+    }
+    const receipt = {
+      schema_version: 1,
+      extraction_id: extractionId,
+      committed_at: new Date().toISOString(),
+      files: inventory,
+    };
+    await write(
+      root,
+      `.agents/private/state/visual-url/${extractionId}/receipt.json`,
+      Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`),
+    );
+    return receipt;
+  } finally {
+    await lock.close();
+    await unlink(resolve(directory, "_publish.lock"));
+  }
+}