Skip to content

stark-ai-de/agent-skills / plugins/stark-ai-developer/skills/visual-reports

visual-reports

Verified

Create and update visual reports with optional native interaction, one guided topic at a time, useful diagrams, concise points, joint comparisons and complete offline HTML/Markdown/JSON exports. Use when richer output helps an authorized answer or the user asks for a visual report; keep small answers in chat. Not production application UI or clinical advice.

FileKindSize
SKILL.mdskill md11.5 KB
agents/openai.yamlconfig779 B
assets/completion-example.mdmarkdown3.2 KB
assets/graphite-grain/configurator.htmlother17.7 KB
assets/graphite-grain/configurator.mjsscript6.9 KB
assets/graphite-grain/relaxed.cssother4.2 KB
assets/openai-icon.pngbinary10.3 KB
assets/openai-icon.svgother318 B
assets/preview.jsscript3.4 KB
assets/report-recipes.mjsscript19.2 KB
assets/report-runtime.cssother16.4 KB
assets/report-runtime.jsscript23.9 KB
assets/report-shell.htmlother14.1 KB
references/comparisons.mdmarkdown4.8 KB
references/filesystem-handoff.mdmarkdown4.7 KB
references/managed-reports.mdmarkdown5.2 KB
references/markdown-input.mdmarkdown3.9 KB
references/model-v2.mdmarkdown10.1 KB
references/renderer.mdmarkdown24.5 KB
references/report-contract.mdmarkdown33.1 KB
references/selection.mdmarkdown4.8 KB
scripts/benchmark.mjsscript2.2 KB
scripts/cache_icon.pyscript9.2 KB
scripts/export-assets.mjsscript4.1 KB
scripts/lib/blocks-v2.mjsscript21.7 KB
scripts/lib/cli.mjsscript3.7 KB
scripts/lib/export-path.mjsscript1.6 KB
scripts/lib/generator-entry.mjsscript472 B
scripts/lib/markdown-input.mjsscript9.8 KB
scripts/lib/preview.mjsscript4.9 KB
scripts/lib/report-state.mjsscript13.4 KB
scripts/lib/report-store.mjsscript7.0 KB
scripts/lib/templates.mjsscript4.7 KB
scripts/render-report.mjsscript40.0 KB
tests/browser-delivery.mjsscript25.4 KB
tests/browser-smoke.pyscript15.5 KB
tests/browser-topics.mjsscript21.1 KB
tests/cache-icon.test.mjsscript5.0 KB
tests/export-assets.test.mjsscript5.5 KB
tests/render-report.test.mjsscript14.3 KB
tests/report-state.test.mjsscript11.7 KB
tests/topics.test.mjsscript6.4 KB
tests/v2.test.mjsscript21.1 KB

scripts/lib/report-store.mjs

View on GitHub
// Local, explicit filesystem writes. SPDX-License-Identifier: Apache-2.0
import { mkdir, open, readFile, rename, rm, lstat, realpath, readdir } from "node:fs/promises";
import path from "node:path";
import { randomUUID, createHash } from "node:crypto";
import { renderReport, validateReport } from "../render-report.mjs";
const revisionPattern = /^\d{13}-[a-f0-9-]{36}$/;
const validRevision = (v) => {
  if (!revisionPattern.test(v)) throw new TypeError("Invalid revision");
  return v;
};
async function regular(file) {
  const stat = await lstat(file);
  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Store file must be regular");
}
async function inspectDirectoryPath(resolved) {
  const volume = path.parse(resolved).root;
  const parts = resolved.slice(volume.length).split(path.sep).filter(Boolean);
  let current = volume;
  for (let index = 0; index < parts.length; index++) {
    current = path.join(current, parts[index]);
    let stat;
    try {
      stat = await lstat(current);
    } catch (error) {
      if (error.code !== "ENOENT") throw error;
      return [
        current,
        ...parts.slice(index + 1).map((part) => (current = path.join(current, part))),
      ];
    }
    if (!stat.isDirectory() || stat.isSymbolicLink() || (await realpath(current)) !== current)
      throw new Error("Store must be a real directory without symlink ancestors");
  }
  return [];
}
async function root(directory, create = false) {
  const resolved = path.resolve(directory);
  const missing = await inspectDirectoryPath(resolved);
  if (missing.length && !create)
    throw Object.assign(new Error("Store directory does not exist"), { code: "ENOENT" });
  for (const directoryPath of missing) {
    try {
      await mkdir(directoryPath, { mode: 0o700 });
    } catch (error) {
      if (error.code !== "EEXIST") throw error;
    }
    const stat = await lstat(directoryPath);
    if (
      !stat.isDirectory() ||
      stat.isSymbolicLink() ||
      (await realpath(directoryPath)) !== directoryPath
    )
      throw new Error("Store must be a real directory without symlink ancestors");
  }
  return resolved;
}
async function readJson(file) {
  await regular(file);
  return JSON.parse(await readFile(file, "utf8"));
}
async function put(file, value) {
  const handle = await open(file, "wx", 0o600);
  try {
    await handle.writeFile(value);
    await handle.sync();
  } finally {
    await handle.close();
  }
}
export async function currentRevision(directory) {
  const base = await root(directory);
  try {
    const current = await readJson(path.join(base, "current.json"));
    validRevision(current.revision);
    if (typeof current.reportId !== "string") throw new Error("Invalid current pointer");
    return current;
  } catch (e) {
    if (e.code === "ENOENT") return null;
    throw e;
  }
}
async function revisionMetadata(directory, revision) {
  const base = await root(directory),
    dir = path.join(base, "revisions", validRevision(revision));
  if ((await realpath(dir)) !== dir) throw new Error("Revision symlink refused");
  const manifest = await readJson(path.join(dir, "revision.json"));
  if (manifest.revision !== revision || !manifest.files)
    throw new Error("Invalid revision manifest");
  if (manifest.parent !== null) validRevision(manifest.parent);
  return { dir, manifest };
}
export async function readRevision(directory, revision) {
  const { dir, manifest } = await revisionMetadata(directory, revision);
  const output = {};
  for (const ext of ["html", "md", "json"]) {
    const file = path.join(dir, `report.${ext}`);
    await regular(file);
    const content = await readFile(file, "utf8");
    if (createHash("sha256").update(content).digest("hex") !== manifest.files[ext])
      throw new Error(`Revision ${ext} checksum mismatch`);
    output[ext] = content;
  }
  return { manifest, ...output };
}
export async function history(directory, { head } = {}) {
  const current = head === undefined ? await currentRevision(directory) : null,
    result = [],
    seen = new Set();
  let revision = head === undefined ? current?.revision : head;
  while (revision) {
    if (seen.has(revision)) throw new Error("Cyclic revision history");
    seen.add(revision);
    const { manifest } = await revisionMetadata(directory, revision);
    result.push(manifest);
    revision = manifest.parent;
  }
  return result;
}
export async function publishRevision(report, directory, { expected = null } = {}) {
  validateReport(report);
  if (expected !== null) validRevision(expected);
  const base = await root(directory, true),
    lock = path.join(base, ".writer-lock");
  try {
    await mkdir(lock, { mode: 0o700 });
  } catch (e) {
    if (e.code === "EEXIST")
      throw new Error(
        `Report store is locked: ${lock}. Inspect the owning process before manual recovery; lock is never stolen.`,
      );
    throw e;
  }
  let temporary;
  try {
    await put(
      path.join(lock, "owner.json"),
      JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }),
    );
    const current = await currentRevision(base);
    if (!current && (await readdir(base)).some((name) => name !== ".writer-lock"))
      throw new Error(
        "Create requires an empty report store; inspect existing contents before recovery",
      );
    if ((current?.revision ?? null) !== expected)
      throw new Error(
        `Stale update: expected ${expected ?? "empty store"}, current ${current?.revision ?? "empty store"}`,
      );
    if (current && current.reportId !== report.id)
      throw new Error("Report id cannot change within a store");
    const output = await renderReport(report);
    const revisions = path.join(base, "revisions");
    await mkdir(revisions, { recursive: true, mode: 0o700 });
    if ((await realpath(revisions)) !== revisions) throw new Error("Revisions symlink refused");
    const revision = `${Date.now()}-${randomUUID()}`;
    temporary = path.join(revisions, `.pending-${randomUUID()}`);
    await mkdir(temporary, { mode: 0o700 });
    const formats = { html: output.html, md: output.markdown, json: output.json };
    const manifest = {
      revision,
      parent: expected,
      reportId: report.id,
      createdAt: new Date().toISOString(),
      files: {},
    };
    for (const [ext, content] of Object.entries(formats)) {
      manifest.files[ext] = createHash("sha256").update(content).digest("hex");
      await put(path.join(temporary, `report.${ext}`), content);
    }
    await put(path.join(temporary, "revision.json"), JSON.stringify(manifest, null, 2) + "\n");
    await rename(temporary, path.join(revisions, revision));
    temporary = undefined;
    // A failure here leaves only an unreferenced complete revision; current stays valid.
    const pointer = path.join(lock, "current.next");
    await put(pointer, JSON.stringify({ revision, reportId: report.id }) + "\n");
    await rename(pointer, path.join(base, "current.json"));
    return manifest;
  } finally {
    if (temporary) await rm(temporary, { recursive: true, force: true });
    await rm(lock, { recursive: true, force: true });
  }
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall