stark-ai-de/agent-skills / plugins/stark-ai-developer/skills/visual-reports
visual-reports
VerifiedCreate 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.
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 });
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |