The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
#!/usr/bin/env node
import { readFileSync, readdirSync } from "node:fs";
import { createRequire } from "node:module";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { featureIndex, sidebarLabel } from "./feature-map.mjs";
import { generateFeatureArtifacts, generatedRoot, writeArtifacts } from "./storybook-feature-index.mjs";
import { checkMaps } from "./check-maps.mjs";
const scriptPath = fileURLToPath(import.meta.url);
const defaultRoot = path.resolve(path.dirname(scriptPath), "..");
const storyRoot = "ui/storybook/stories";
const statuses = ["current", "proposed", "historical", "mixed", "unreviewed"];
const implementations = ["production", "prototype", "mixed", "guide", "unreviewed"];
const boundaries = ["fixtures", "fixture-server", "static", "unreviewed"];
const annotationFields = new Set(["capabilities", "status", "implementation", "boundary", "notes", "home", "exception", "replacement"]);
const specialHomes = { overview: "Overview", "design-proposals": "Design proposals", foundations: "Foundations" };
function files(root, dir) {
return readdirSync(path.join(root, dir), { withFileTypes: true }).flatMap(entry => {
const name = `${dir}/${entry.name}`;
return entry.isDirectory() ? files(root, name) : [name];
}).sort();
}
function literal(node, label) {
if (!node) throw new Error(`${label}: expected literal metadata`);
if (["TSAsExpression", "TSSatisfiesExpression"].includes(node.type)) return literal(node.expression, label);
if (["StringLiteral", "BooleanLiteral", "NumericLiteral"].includes(node.type)) return node.value;
if (node.type === "ArrayExpression") return node.elements.map(element => literal(element, label));
if (node.type === "ObjectExpression") {
const result = {};
for (const property of node.properties) {
const key = property.key?.name ?? property.key?.value;
if (property.type !== "ObjectProperty" || property.computed || typeof key !== "string" || Object.hasOwn(result, key) || key === "__proto__") {
throw new Error(`${label}: metadata must use unique literal properties`);
}
result[key] = literal(property.value, label);
}
return result;
}
throw new Error(`${label}: metadata must be literal; expressions are not executed`);
}
function annotation(csf, file) {
const parameters = csf._metaAnnotations.parameters;
if (parameters?.type !== "ObjectExpression") throw new Error(`${file}: declare parameters.paperclip as literal metadata`);
const matches = parameters.properties.filter(property => (property.key?.name ?? property.key?.value) === "paperclip");
if (matches.length !== 1) throw new Error(`${file}: expected one parameters.paperclip annotation`);
const property = matches[0];
if (property.type !== "ObjectProperty" || property.computed) throw new Error(`${file}: paperclip must be a literal property`);
if (parameters.properties.slice(parameters.properties.indexOf(property) + 1).some(property => property.type === "SpreadElement" || property.computed)) {
throw new Error(`${file}: paperclip metadata must follow parameter spreads and computed properties`);
}
const value = literal(property.value, file);
if (!value || Array.isArray(value) || typeof value !== "object") throw new Error(`${file}: paperclip metadata must be an object`);
for (const key of Object.keys(value)) if (!annotationFields.has(key)) throw new Error(`${file}: unknown paperclip field ${key}`);
return value;
}
export function scanStories(root = defaultRoot) {
const require = createRequire(path.join(root, "ui/package.json"));
const { loadCsf } = require("storybook/internal/csf-tools");
return files(root, storyRoot).filter(file => /\.stories\.(ts|tsx|mdx)$/.test(file)).map(file => {
const csf = loadCsf(readFileSync(path.join(root, file), "utf8"), { fileName: file, makeTitle: title => title }).parse();
return { file, title: csf.meta.title, metaId: csf.meta.id, ids: csf.stories.map(story => story.id), plays: csf.stories.filter(story => story.__stats?.play).length, annotation: annotation(csf, file) };
});
}
export function storyHome(entry) {
return entry.home ?? (typeof entry.capabilities?.[0] === "string" ? entry.capabilities[0].split("/")[0] : undefined) ?? (entry.implementation === "guide" ? "overview" : "foundations");
}
export function catalogFromStories(stories, index) {
const navigation = new Map(index.sections.flatMap(section => section.features.map(feature => [feature.id, `${sidebarLabel(section.title)}/${sidebarLabel(feature.title)}`])));
return { version: 2, entries: stories.map(story => {
const entry = { status: "unreviewed", implementation: "unreviewed", boundary: "unreviewed", notes: "", ...story.annotation, file: story.file, stableId: story.metaId, sidebarTitle: story.title };
const prefix = navigation.get(storyHome(entry)) ?? specialHomes[storyHome(entry)];
return { ...entry, purpose: story.title?.startsWith(`${prefix}/`) ? story.title.slice(prefix.length + 1) : story.title };
}) };
}
export function validateCatalog(catalog, stories, index) {
const errors = [];
const refs = new Set(index.sections.flatMap(section => section.features.flatMap(feature => feature.capabilities.map(capability => capability.id))));
const navigation = new Map(index.sections.flatMap(section => section.features.map(feature => [feature.id, `${sidebarLabel(section.title)}/${sidebarLabel(feature.title)}`])));
const byFile = new Map(stories.map(story => [story.file, story]));
for (const entry of catalog.entries) {
const label = entry.file;
if (!statuses.includes(entry.status)) errors.push(`${label}: invalid product status`);
if (!implementations.includes(entry.implementation)) errors.push(`${label}: invalid implementation`);
if (!boundaries.includes(entry.boundary)) errors.push(`${label}: invalid data boundary`);
if (typeof entry.notes !== "string") errors.push(`${label}: notes must be text`);
if (!Array.isArray(entry.capabilities) || entry.capabilities.some(ref => typeof ref !== "string")) { errors.push(`${label}: capabilities must be an array of IDs`); continue; }
if (entry.home !== undefined && !["foundations", "design-proposals"].includes(entry.home)) errors.push(`${label}: only shared foundations and design proposals may override the capability home`);
if (entry.exception !== undefined && (typeof entry.exception !== "string" || !entry.exception.trim())) errors.push(`${label}: exception must be nonempty text`);
if (entry.home === "foundations" && !entry.exception) errors.push(`${label}: foundation home needs an explicit reason`);
if (entry.home === "design-proposals") {
if (entry.status !== "proposed") errors.push(`${label}: design proposal home requires proposed status`);
if (!entry.exception) errors.push(`${label}: design proposal home needs an explicit staging reason`);
}
for (const ref of entry.capabilities) if (!refs.has(ref)) errors.push(`${label}: unknown feature capability ${ref}`);
if (!entry.capabilities.length && !entry.exception) errors.push(`${label}: unmapped story needs an explicit reason`);
if (entry.capabilities.length !== new Set(entry.capabilities).size) errors.push(`${label}: duplicate capability references`);
const area = storyHome(entry);
const prefix = navigation.get(area) ?? specialHomes[area];
if (!label.startsWith(`${storyRoot}/${area}/`)) errors.push(`${label}: story must live in its primary feature folder ${area}`);
if (!prefix || typeof entry.sidebarTitle !== "string" || !entry.sidebarTitle.startsWith(`${prefix}/`)) errors.push(`${label}: sidebar title must match its feature-map home`);
if (typeof entry.stableId !== "string" || !entry.stableId.trim()) errors.push(`${label}: explicit meta ID is required`);
if (entry.replacement !== undefined && !byFile.has(entry.replacement)) errors.push(`${label}: replacement story is missing`);
}
const metaIds = stories.map(story => story.metaId);
const ids = [...stories.flatMap(story => story.ids), ...index.sections.flatMap(section => section.features.map(feature => `feature-map-${feature.id}--overview`))];
if (metaIds.length !== new Set(metaIds).size || ids.length !== new Set(ids).size) errors.push("Duplicate story IDs");
return errors;
}
function cell(value) { return String(value).replaceAll("|", "\\|").replaceAll("\n", " "); }
export function renderIndex(catalog, stories, index) {
const byFile = new Map(stories.map(story => [story.file, story]));
const groups = new Map();
for (const entry of catalog.entries) {
const home = storyHome(entry);
const area = ["foundations", "overview"].includes(home) ? "foundations-and-guides" : home;
if (!groups.has(area)) groups.set(area, []);
groups.get(area).push(entry);
}
const lines = ["# Storybook by feature", "", "Generated from story annotations and feature recipes. Do not edit this file.", "",
"[Contract and maintenance](../storybook-map/README.md) · [Verification routes](verification.md)", "",
`${stories.length} story files; ${stories.reduce((n, story) => n + story.ids.length, 0)} indexed stories. Counts describe inventory, not passed tests or complete feature coverage.`, "",
"Status describes product alignment; implementation describes the rendered subject; boundary describes simulated data. Limitations are authored alongside each story. Classification is not executed evidence. Related capabilities cross-list one canonical story file.", ""];
const homes = [
{ id: "design-proposals", title: "Proposed design system", section: "Design proposals", description: "Staged design work for review. These examples retain capability references but do not count as current product coverage." },
...index.sections.flatMap(section => section.features.map(feature => ({ ...feature, section: section.title }))),
];
homes.push({ id: "foundations-and-guides", title: "Shared foundations and guides", section: "Foundations", description: "Shared components and contributor guidance outside the product feature index." });
let currentSection;
for (const feature of homes) {
const area = feature.id;
const entries = groups.get(area) ?? [];
if (feature.section !== currentSection) {
lines.push(`## ${feature.section}`, "");
currentSection = feature.section;
}
lines.push(`### ${feature.title}`, "", feature.description, "", ...(!["foundations-and-guides", "design-proposals"].includes(area) ? [`[Feature recipe](../feature-map/${area}.md)`, ""] : []));
if (!entries.length) lines.push("No primary story suite. Check capability lookup below for related examples; this does not imply a missing product feature.", "");
else lines.push(
"| Story suite | Capabilities | Product / implementation / data | Stories / play functions | Review note |",
"| --- | --- | --- | --- | --- |");
for (const entry of entries.sort((a, b) => a.file.localeCompare(b.file))) {
const story = byFile.get(entry.file);
lines.push(`| [${cell(story.title)}](../../${entry.file}) | ${entry.capabilities.map(ref => `\`${ref}\``).join(", ") || cell(entry.exception)} | ${entry.status} / ${entry.implementation} / ${entry.boundary} | ${story.ids.length} / ${story.plays} | ${cell(entry.notes)} |`);
}
lines.push("");
}
lines.push("## Capability lookup", "", "References are navigation links, not proof of parity. An absent link means no cataloged story, not a missing product feature. CLI/operator capabilities may need no Storybook example.", "");
for (const ref of index.sections.flatMap(section => section.features.flatMap(feature => feature.capabilities.map(capability => capability.id)))) {
const entries = catalog.entries.filter(entry => entry.capabilities.includes(ref));
lines.push(`- \`${ref}\`: ${entries.length ? entries.map(entry => `[${cell(byFile.get(entry.file).title)}](../../${entry.file}) (${entry.status})`).join(", ") : "No cataloged story."}`);
}
return lines.join("\n") + "\n";
}
export function renderVerification(catalog, index) {
const examples = catalog.entries.filter(entry => entry.implementation !== "guide" && !["historical", "proposed"].includes(entry.status));
const capabilities = index.sections.flatMap(section => section.features.flatMap(feature => feature.capabilities));
const missing = capabilities.filter(capability => !examples.some(entry => entry.capabilities.includes(capability.id)));
const lines = ["# Storybook verification routes", "", "Generated from story annotations and feature recipes. Associations are navigation, not proof of passing tests.", "",
`${capabilities.length} capabilities; ${missing.length} without a current, mixed or unreviewed example. Historical examples, proposals and guides do not remove gaps.`, "",
"## Capabilities without examples", ""];
for (const capability of missing) {
const area = capability.id.split("/")[0];
lines.push(`- [${capability.id}](../feature-map/${area}.md): ${capability.verification?.storybook ?? "No example associated. Inspect the feature recipe to select verification."}`);
}
lines.push("", "## Authored verification guidance", "");
for (const capability of capabilities.filter(capability => capability.verification)) {
const route = capability.verification;
lines.push(`### ${capability.id}`, "", `Scope: ${route.scope}`, "", `Storybook: ${route.storybook}`, "", `Production: ${route.production}`, "", `Sources: ${route.sources}`, "");
}
return lines.join("\n");
}
export function generateStorybook(root = defaultRoot, { write = true } = {}) {
const mapErrors = checkMaps(root).errors;
if (mapErrors.length) throw new Error(mapErrors.join("\n"));
const index = featureIndex(root);
const stories = scanStories(root);
const catalog = catalogFromStories(stories, index);
const errors = validateCatalog(catalog, stories, index);
if (errors.length) throw new Error(errors.join("\n"));
if (write) {
generateFeatureArtifacts(root, index);
writeArtifacts(root, new Map([
[`${generatedRoot}/catalog.json`, JSON.stringify(catalog, null, 2) + "\n"],
["maps/generated/storybook.md", renderIndex(catalog, stories, index)],
["maps/generated/verification.md", renderVerification(catalog, index)],
]));
}
return { catalog, stories, index };
}
if (process.argv[1] && path.resolve(process.argv[1]) === scriptPath) {
const args = process.argv.slice(2);
if (args.some(arg => !["--write", "--check"].includes(arg)) || args.length > 1) throw new Error("Usage: node scripts/storybook-catalog.mjs [--write | --check]");
const { stories } = generateStorybook(defaultRoot, { write: !args.includes("--check") });
console.log(`Storybook map: ${stories.length} files, ${stories.reduce((n, story) => n + story.ids.length, 0)} stories. Structure only; no runtime proof.`);
}