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
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync, rmSync } from "node:fs";
import path from "node:path";
import { test } from "node:test";
import { catalogFromStories, generateStorybook, renderIndex, renderVerification, scanStories, validateCatalog } from "./storybook-catalog.mjs";
import { featureIndex } from "./feature-map.mjs";
import { mapFixture } from "./map-test-fixture.mjs";
function inspect(f) {
const index = featureIndex(f.root);
const stories = scanStories(f.root);
const catalog = catalogFromStories(stories, index);
return { catalog, stories, index, errors: validateCatalog(catalog, stories, index) };
}
test("source annotations assemble an inventory without a registry or review stamps", t => {
const f = mapFixture(t);
const result = inspect(f);
assert.deepEqual(result.errors, []);
assert.equal(result.catalog.entries[0].purpose, "task");
assert.equal(result.catalog.entries[0].status, "unreviewed");
assert.equal(result.catalog.entries[0].stableId, "stable-task");
assert.equal(Object.hasOwn(result.catalog.entries[0], "fingerprint"), false);
assert.equal(Object.hasOwn(result.catalog.entries[0], "reviewedAt"), false);
f.story("new");
assert.equal(inspect(f).catalog.entries.length, 2);
rmSync(path.join(f.root, f.file));
assert.equal(inspect(f).catalog.entries.length, 1);
});
test("unknown capabilities, invalid annotations and inappropriate homes fail", t => {
const f = mapFixture(t);
f.story("task", { capabilities: ["tasks/missing"] });
assert.match(inspect(f).errors.join("\n"), /unknown feature capability/);
f.story("task", { capabilities: [], status: "passed" });
assert.match(inspect(f).errors.join("\n"), /invalid product status/);
assert.match(inspect(f).errors.join("\n"), /explicit reason/);
f.story("task", { capabilities: "tasks/create" });
assert.match(inspect(f).errors.join("\n"), /array of IDs/);
f.story("task", { capabilities: ["tasks/create"] }, { title: "Other/Task" });
assert.match(inspect(f).errors.join("\n"), /sidebar title/);
});
test("metadata is parsed without executing code or accepting obsolete bookkeeping fields", t => {
const f = mapFixture(t);
f.write(f.file, `export default { id: 'task', title: 'Work/Tasks/Test', parameters: { paperclip: (() => { throw new Error('executed'); })() } }; export const Empty = {};`);
assert.throws(() => scanStories(f.root), /expressions are not executed/);
f.story("task", { capabilities: ["tasks/create"], fingerprint: "old" });
assert.throws(() => scanStories(f.root), /unknown paperclip field fingerprint/);
f.write(f.file, "export default { id: 'task', title: 'Work/Tasks/Test', parameters: { paperclip: { capabilities: [], capabilities: [] } } }; export const Empty = {};");
assert.throws(() => scanStories(f.root), /unique literal properties/);
});
test("parameter spreads cannot silently overwrite a source annotation", t => {
const f = mapFixture(t);
f.write(f.file, "export default { id: 'task', title: 'Work/Tasks/Test', parameters: { paperclip: { capabilities: [] }, ...other } }; export const Empty = {};");
assert.throws(() => scanStories(f.root), /must follow parameter spreads/);
f.write(f.file, "export default { id: 'task', title: 'Work/Tasks/Test', parameters: { paperclip: { capabilities: [] }, [key]: other } }; export const Empty = {};");
assert.throws(() => scanStories(f.root), /must follow parameter spreads/);
f.write(f.file, "export default { id: 'task', title: 'Work/Tasks/Test', parameters: { ['paperclip']: { capabilities: [] } } }; export const Empty = {};");
assert.throws(() => scanStories(f.root), /must be a literal property/);
});
test("foundations preserve home and cross-capability references", t => {
const f = mapFixture(t);
f.story("control", { capabilities: ["tasks/create"], home: "foundations", exception: "Shared control", implementation: "production" }, { area: "foundations", title: "Foundations/Control" });
const { catalog, errors } = inspect(f);
assert.deepEqual(errors, []);
assert.equal(catalog.entries.find(entry => entry.stableId === "stable-control").home, "foundations");
f.story("control", { capabilities: ["tasks/create"], home: "foundations" }, { area: "foundations", title: "Foundations/Control" });
assert.match(inspect(f).errors.join("\n"), /foundation home needs an explicit reason/);
});
test("design proposals keep stable IDs and capability links in a separate catalog section without filling coverage gaps", t => {
const f = mapFixture(t);
const originalIds = scanStories(f.root)[0].ids;
rmSync(path.join(f.root, f.file));
f.story("task", {
home: "design-proposals",
status: "proposed",
capabilities: ["tasks/create", "tasks/discussion"],
implementation: "production",
boundary: "fixtures",
exception: "Opt-in task row refresh awaiting design review and application rollout.",
}, { area: "design-proposals", title: "Design proposals/Tasks/Task row" });
const { catalog, stories, index, errors } = inspect(f);
assert.deepEqual(errors, []);
assert.deepEqual(stories[0].ids, originalIds);
assert.equal(catalog.entries[0].home, "design-proposals");
assert.equal(catalog.entries[0].purpose, "Tasks/Task row");
const report = renderIndex(catalog, stories, index);
const proposalSection = report.split("## Design proposals\n")[1].split("## Work\n")[0];
assert.match(proposalSection, /Design proposals\/Tasks\/Task row/);
assert.doesNotMatch(report, /feature-map\/design-proposals\.md/);
assert.match(report, /- `tasks\/create`: .*\(proposed\)/);
assert.match(report, /- `tasks\/discussion`: .*\(proposed\)/);
assert.match(renderVerification(catalog, index), /2 without a current, mixed or unreviewed example/);
});
test("design proposal homes require proposed status, a staging reason and their own navigation", t => {
const f = mapFixture(t);
const metadata = { home: "design-proposals", status: "proposed", capabilities: ["tasks/create"], exception: "Staged refresh for review." };
const options = { area: "design-proposals", title: "Design proposals/Tasks/Task row" };
for (const status of ["current", "mixed", "unreviewed", "historical"]) {
f.story("proposal", { ...metadata, status }, options);
assert.match(inspect(f).errors.join("\n"), /design proposal home requires proposed status/);
}
f.story("proposal", { ...metadata, exception: undefined }, options);
assert.match(inspect(f).errors.join("\n"), /design proposal home needs an explicit staging reason/);
f.story("proposal", metadata, { ...options, title: "Work/Tasks/Task row" });
assert.match(inspect(f).errors.join("\n"), /sidebar title/);
f.story("misplaced", metadata, { title: options.title });
assert.match(inspect(f).errors.join("\n"), /primary feature folder design-proposals/);
});
test("duplicate IDs, missing replacement references and collisions with generated guides fail", t => {
const f = mapFixture(t);
f.story("other", { capabilities: ["tasks/create"] }, { id: "stable-task" });
assert.match(inspect(f).errors.join("\n"), /Duplicate story IDs/);
f.story("other", { capabilities: ["tasks/create"] }, { id: "feature-map-tasks", exports: "export const Overview = {};" });
assert.match(inspect(f).errors.join("\n"), /Duplicate story IDs/);
f.story("other", { capabilities: ["tasks/create"], replacement: "missing.stories.tsx" });
assert.match(inspect(f).errors.join("\n"), /replacement story is missing/);
});
test("recipe, component and shared fixture edits need no fingerprint acknowledgements", t => {
const f = mapFixture(t);
const before = inspect(f).catalog;
f.write("ui/src/Task.tsx", "export const Task = () => null;");
f.write("ui/storybook/.storybook/preview-base.tsx", "export default { parameters: { changed: true } };");
const file = "maps/feature-map/tasks.md";
f.write(file, readFileSync(path.join(f.root, file), "utf8").replace("discussion work.", "Discuss revised behavior."));
assert.deepEqual(inspect(f).catalog, before);
assert.deepEqual(inspect(f).errors, []);
});
test("check mode needs no generated outputs and generation leaves authored files intact", t => {
const f = mapFixture(t);
const before = readFileSync(path.join(f.root, f.file), "utf8");
generateStorybook(f.root, { write: false });
assert.equal(existsSync(path.join(f.root, "ui/storybook/generated")), false);
generateStorybook(f.root);
assert.ok(existsSync(path.join(f.root, "ui/storybook/generated/catalog.json")));
assert.ok(existsSync(path.join(f.root, "maps/generated/verification.md")));
assert.equal(readFileSync(path.join(f.root, f.file), "utf8"), before);
const first = readFileSync(path.join(f.root, "maps/generated/storybook.md"), "utf8");
generateStorybook(f.root);
assert.equal(readFileSync(path.join(f.root, "maps/generated/storybook.md"), "utf8"), first);
});
test("gap reports combine associations with local verification scope and retain historical gaps", t => {
const f = mapFixture(t);
f.story("task", { capabilities: ["tasks/create"], status: "historical" });
const file = "maps/feature-map/tasks.md";
f.write(file, readFileSync(path.join(f.root, file), "utf8") + "\n### Storybook verification\n\n#### `create`\n\nScope: cli\nStorybook: No story required for the command.\nProduction: Run the command.\nSources: Inspect the CLI.\n");
const { catalog, index } = inspect(f);
const report = renderVerification(catalog, index);
assert.match(report, /2 without a current, mixed or unreviewed example/);
assert.match(report, /No story required for the command/);
assert.match(report, /Production: Run the command/);
});
test("the CSF parser preserves explicit IDs, export filtering and play counts", t => {
const f = mapFixture(t);
f.write(f.file, `import type { Meta } from '@storybook/react-vite';
const meta = { id: 'stable-task', title: 'Work/Tasks/Create', excludeStories: ['helper'], parameters: { paperclip: { capabilities: ['tasks/create'] } } } satisfies Meta;
export default meta;
export const helper = {};
export const Empty = {};
export const Filled = { play: async () => {} };
`);
const [story] = scanStories(f.root);
assert.deepEqual(story.ids, ["stable-task--empty", "stable-task--filled"]);
assert.equal(story.plays, 1);
});
test("independent story and feature branches merge in either order with identical clean generated maps", t => {
const f = mapFixture(t);
f.write(".gitignore", readFileSync(path.join(f.root, ".gitignore"), "utf8") + "node_modules\n");
const git = (...args) => execFileSync("git", ["-c", "user.name=Map test", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args], {
cwd: f.root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" },
});
git("init", "-b", "main");
git("add", ".");
git("commit", "-qm", "Initial recipes and story");
git("checkout", "-b", "story-change");
f.story("task", { capabilities: ["tasks/create"], notes: "Retain creation draft." }, { exports: "export const Empty = {}; export const Draft = {};" });
git("add", "."); git("commit", "-qm", "Add task draft example");
git("checkout", "-b", "feature-addition", "main");
f.feature("goals", "Goals", ["hierarchy"], { order: 20 });
f.story("goal", { capabilities: ["goals/hierarchy"] }, { area: "goals", title: "Work/Goals/Goal" });
git("add", "."); git("commit", "-qm", "Add goal capability and example");
const results = [];
for (const [first, second] of [["story-change", "feature-addition"], ["feature-addition", "story-change"]]) {
git("checkout", "-b", `merged-${first}`, "main");
git("merge", "--no-edit", first);
git("merge", "--no-edit", second);
const result = generateStorybook(f.root);
assert.equal(git("status", "--porcelain"), "");
assert.deepEqual(result.stories.flatMap(story => story.ids).sort(), ["stable-goal--empty", "stable-task--draft", "stable-task--empty"]);
results.push(["ui/storybook/generated/catalog.json", "ui/storybook/generated/feature-index.json", "maps/generated/storybook.md", "maps/generated/verification.md", "ui/storybook/.storybook/preview.tsx"].map(file => readFileSync(path.join(f.root, file), "utf8")));
}
assert.deepEqual(results[0], results[1]);
});