@deftai/directive-core 0.55.0

package/dist/render/project-render.js

@@ -0,0 +1,169 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
+import { PROJECT_LIFECYCLE_FOLDERS, SKELETON_NARRATIVES } from "./constants.js";
+import { splitCamel, splitWords } from "./text-utils.js";
+export function scanLifecycleFolders(vbriefDir) {
+    const items = [];
+    for (const folderName of PROJECT_LIFECYCLE_FOLDERS) {
+        const folder = join(vbriefDir, folderName);
+        if (!existsSync(folder))
+            continue;
+        let files;
+        try {
+            files = readdirSync(folder)
+                .filter((n) => n.endsWith(".vbrief.json"))
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const vbriefFile of files) {
+            const full = join(folder, vbriefFile);
+            try {
+                const data = JSON.parse(readFileSync(full, "utf8"));
+                const plan = (data.plan ?? {});
+                const title = String(plan.title ?? vbriefFile.replace(/\.vbrief\.json$/, ""));
+                const status = String(plan.status ?? folderName);
+                const references = plan.references;
+                const item = {
+                    id: vbriefFile.replace(/\.vbrief\.json$/, "").replace(/\.vbrief$/, ""),
+                    title,
+                    status,
+                    metadata: {
+                        source_path: `${folderName}/${vbriefFile}`,
+                        lifecycle_folder: folderName,
+                    },
+                };
+                if (Array.isArray(references) && references.length > 0) {
+                    item.metadata.references = references;
+                }
+                items.push(item);
+            }
+            catch {
+                items.push({
+                    id: vbriefFile.replace(/\.vbrief\.json$/, "").replace(/\.vbrief$/, ""),
+                    title: `[unreadable] ${vbriefFile}`,
+                    status: "draft",
+                    metadata: {
+                        source_path: `${folderName}/${vbriefFile}`,
+                        lifecycle_folder: folderName,
+                        error: "Failed to read or parse file",
+                    },
+                });
+            }
+        }
+    }
+    return items;
+}
+export function flagStaleNarratives(narratives, completedItems) {
+    if (completedItems.length === 0 || Object.keys(narratives).length === 0) {
+        if (completedItems.length >= 3) {
+            return [
+                `${completedItems.length} scopes completed since last narrative update -- review recommended`,
+            ];
+        }
+        return [];
+    }
+    const flags = [];
+    const flaggedNarratives = new Set();
+    for (const narrativeKey of Object.keys(narratives).sort()) {
+        const keyWords = new Set(splitCamel(narrativeKey).filter((w) => w.length > 3));
+        if (keyWords.size === 0)
+            continue;
+        for (const item of completedItems) {
+            const titleLower = item.title.toLowerCase();
+            const titleWords = new Set(splitWords(titleLower));
+            const overlap = [...keyWords].filter((w) => titleWords.has(w));
+            if (overlap.length > 0) {
+                flags.push(`Narrative '${narrativeKey}' may be stale: completed scope '${item.title}' shares topics (${overlap.sort().join(", ")})`);
+                flaggedNarratives.add(narrativeKey);
+            }
+        }
+    }
+    if (completedItems.length >= 3 && flaggedNarratives.size === 0) {
+        flags.push(`${completedItems.length} scopes completed since last narrative update -- review recommended`);
+    }
+    return flags.sort();
+}
+export function createSkeleton(items, now) {
+    const completedItems = items.filter((i) => i.status === "completed");
+    const stalenessFlags = flagStaleNarratives({ ...SKELETON_NARRATIVES }, completedItems);
+    return {
+        vBRIEFInfo: {
+            version: EMITTED_VBRIEF_VERSION,
+            description: "Project definition -- synthesized gestalt of the project",
+            created: now,
+            updated: now,
+        },
+        plan: {
+            title: "PROJECT-DEFINITION",
+            status: "running",
+            narratives: { ...SKELETON_NARRATIVES },
+            items,
+            metadata: { staleness_flags: stalenessFlags },
+        },
+    };
+}
+/** Regenerate PROJECT-DEFINITION.vbrief.json (mirrors ``scripts/project_render.render_project_definition``). */
+export function renderProjectDefinition(vbriefDir, options = {}) {
+    const nowDate = options.now ?? new Date();
+    const now = nowDate.toISOString().replace(/\.\d{3}Z$/, "Z");
+    const projectDefPath = join(vbriefDir, "PROJECT-DEFINITION.vbrief.json");
+    const items = scanLifecycleFolders(vbriefDir);
+    const createdNew = !existsSync(projectDefPath);
+    let projectDef;
+    if (existsSync(projectDefPath)) {
+        try {
+            projectDef = JSON.parse(readFileSync(projectDefPath, "utf8"));
+        }
+        catch (exc) {
+            return [false, `✗ Failed to read ${projectDefPath}: ${String(exc)}`];
+        }
+        const plan = (projectDef.plan ?? {});
+        plan.items = items;
+        if (typeof projectDef.vBRIEFInfo !== "object" || projectDef.vBRIEFInfo === null) {
+            projectDef.vBRIEFInfo = {};
+        }
+        projectDef.vBRIEFInfo.updated = now;
+        const narratives = typeof plan.narratives === "object" &&
+            plan.narratives !== null &&
+            !Array.isArray(plan.narratives)
+            ? plan.narratives
+            : {};
+        const completedItems = items.filter((i) => i.status === "completed");
+        const flags = flagStaleNarratives(narratives, completedItems);
+        if (typeof plan.metadata !== "object" ||
+            plan.metadata === null ||
+            Array.isArray(plan.metadata)) {
+            plan.metadata = {};
+        }
+        plan.metadata.staleness_flags = flags;
+        projectDef.plan = plan;
+    }
+    else {
+        projectDef = createSkeleton(items, now);
+    }
+    mkdirSync(vbriefDir, { recursive: true });
+    writeFileSync(projectDefPath, `${JSON.stringify(projectDef, null, 2)}\n`, "utf8");
+    const itemCount = items.length;
+    const planMeta = (projectDef.plan?.metadata ?? {});
+    const flagCount = Array.isArray(planMeta.staleness_flags) ? planMeta.staleness_flags.length : 0;
+    const action = createdNew ? "created" : "updated";
+    const parts = [`✓ PROJECT-DEFINITION.vbrief.json ${action} (${itemCount} scope items)`];
+    if (flagCount > 0)
+        parts.push(`⚠ ${flagCount} staleness flag(s) -- agent review recommended`);
+    return [true, parts.join("\n")];
+}
+/** CLI entry (mirrors ``scripts/project_render.main``). */
+export function main(argv) {
+    if (argv.length > 1) {
+        process.stderr.write("Usage: project_render.py [vbrief_dir]\n");
+        return 2;
+    }
+    const vbriefDir = argv[0] ?? "vbrief";
+    const [ok, message] = renderProjectDefinition(vbriefDir);
+    process.stdout.write(`${message}\n`);
+    return ok ? 0 : 1;
+}
+//# sourceMappingURL=project-render.js.map

package/dist/render/roadmap-render.d.ts

@@ -0,0 +1,8 @@
+/** Generate ROADMAP.md content (mirrors ``scripts/roadmap_render.generate_roadmap_content``). */
+export declare function generateRoadmapContent(pendingDir: string, completedDir?: string): string;
+export type RenderRoadmapResult = readonly [boolean, string];
+export declare function renderRoadmap(pendingDir: string, outPath: string, completedDir?: string): RenderRoadmapResult;
+export declare function checkDrift(pendingDir: string, roadmapPath: string): RenderRoadmapResult;
+/** CLI entry (mirrors ``scripts/roadmap_render.main``). */
+export declare function main(argv: readonly string[]): number;
+//# sourceMappingURL=roadmap-render.d.ts.map

package/dist/render/roadmap-render.js

@@ -0,0 +1,387 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { MIGRATOR_METADATA_KEY, ROADMAP_BANNER } from "./constants.js";
+import { phaseSortKey } from "./text-utils.js";
+function scopeMetadataRank(plan) {
+    const metadata = plan.metadata;
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata))
+        return null;
+    const rank = metadata.rank;
+    if (typeof rank === "boolean")
+        return null;
+    if (typeof rank === "number" && Number.isInteger(rank))
+        return rank;
+    if (typeof rank === "string") {
+        const trimmed = rank.trim();
+        const parsed = Number.parseInt(trimmed, 10);
+        if (!Number.isNaN(parsed) && String(parsed) === trimmed)
+            return parsed;
+    }
+    return null;
+}
+function scopeRankSortKey(vbrief) {
+    const plan = (vbrief.plan ?? {});
+    const rank = scopeMetadataRank(plan);
+    if (rank === null)
+        return [1, 0];
+    return [0, rank];
+}
+function loadVbriefs(folder) {
+    if (!existsSync(folder))
+        return [];
+    let files;
+    try {
+        files = readdirSync(folder)
+            .filter((n) => n.endsWith(".vbrief.json"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const vbriefs = [];
+    for (const f of files) {
+        try {
+            const data = JSON.parse(readFileSync(join(folder, f), "utf8"));
+            data._source_file = f;
+            vbriefs.push(data);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    vbriefs.sort((a, b) => {
+        const [ba, ra] = scopeRankSortKey(a);
+        const [bb, rb] = scopeRankSortKey(b);
+        return ba - bb || ra - rb;
+    });
+    return vbriefs;
+}
+function extractIssueRefs(references) {
+    if (!Array.isArray(references))
+        return [];
+    const issues = [];
+    for (const ref of references) {
+        if (typeof ref !== "object" || ref === null || Array.isArray(ref))
+            continue;
+        const r = ref;
+        const refId = r.id;
+        if (typeof refId === "string" && refId.startsWith("#")) {
+            issues.push(refId);
+            continue;
+        }
+        for (const key of ["uri", "url"]) {
+            const url = r[key];
+            if (typeof url === "string" && url.includes("/issues/")) {
+                const num = url.replace(/\/+$/, "").split("/").pop() ?? "";
+                if (/^\d+$/.test(num)) {
+                    issues.push(`#${num}`);
+                    break;
+                }
+            }
+        }
+    }
+    return issues;
+}
+function readEdgeEndpoints(edge) {
+    if (typeof edge !== "object" || edge === null || Array.isArray(edge))
+        return ["", ""];
+    const e = edge;
+    const frm = String(e.from ?? e.source ?? "") || "";
+    const to = String(e.to ?? e.target ?? "") || "";
+    return [frm, to];
+}
+function buildEdgeMap(vbrief) {
+    const plan = (vbrief.plan ?? {});
+    const edges = plan.edges;
+    if (!Array.isArray(edges))
+        return {};
+    const depMap = {};
+    for (const edge of edges) {
+        const [frm, to] = readEdgeEndpoints(edge);
+        if (frm && to) {
+            if (!depMap[to])
+                depMap[to] = [];
+            depMap[to].push(frm);
+        }
+    }
+    return depMap;
+}
+function topoSortItems(items, depMap) {
+    if (items.length === 0)
+        return [];
+    const idToItem = new Map();
+    const itemIds = [];
+    for (let i = 0; i < items.length; i += 1) {
+        const item = items[i];
+        const id = String(item.id ?? `_anon_${i}`);
+        idToItem.set(id, item);
+        itemIds.push(id);
+    }
+    const depths = {};
+    const depth = (itemId, visited = null) => {
+        if (itemId in depths)
+            return depths[itemId] ?? 0;
+        const vis = visited ?? new Set();
+        if (vis.has(itemId))
+            return 0;
+        vis.add(itemId);
+        const deps = depMap[itemId] ?? [];
+        const inScope = deps.filter((d) => idToItem.has(d));
+        if (inScope.length === 0) {
+            depths[itemId] = 0;
+            return 0;
+        }
+        const result = Math.max(...inScope.map((d) => depth(d, vis))) + 1;
+        depths[itemId] = result;
+        return result;
+    };
+    for (const iid of itemIds)
+        depth(iid);
+    const sortedIds = [...itemIds].sort((a, b) => (depths[a] ?? 0) - (depths[b] ?? 0) || itemIds.indexOf(a) - itemIds.indexOf(b));
+    return sortedIds.map((id) => idToItem.get(id));
+}
+function renderItem(item, depMap, indent = 0) {
+    const lines = [];
+    const itemId = String(item.id ?? "");
+    const title = String(item.title ?? "Untitled");
+    const status = String(item.status ?? "");
+    const prefix = `${"  ".repeat(indent)}- `;
+    const parts = [];
+    if (itemId)
+        parts.push(`**${itemId}**`);
+    parts.push(title);
+    if (status)
+        parts.push(`\`[${status}]\``);
+    const deps = depMap[itemId] ?? [];
+    if (deps.length > 0)
+        parts.push(`(depends on: ${[...deps].sort().join(", ")})`);
+    lines.push(`${prefix}${parts.join(" -- ")}`);
+    const subItems = item.subItems;
+    if (Array.isArray(subItems) && subItems.length > 0) {
+        const subs = subItems.filter((s) => typeof s === "object" && s !== null && !Array.isArray(s));
+        const sortedSubs = topoSortItems(subs, depMap);
+        for (const sub of sortedSubs)
+            lines.push(...renderItem(sub, depMap, indent + 1));
+    }
+    return lines;
+}
+function migratorMetadata(plan) {
+    const metadata = plan.metadata;
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata))
+        return {};
+    const bucket = metadata[MIGRATOR_METADATA_KEY];
+    if (typeof bucket === "object" && bucket !== null && !Array.isArray(bucket)) {
+        return bucket;
+    }
+    return {};
+}
+function migratorField(plan, key) {
+    const bucket = migratorMetadata(plan);
+    const value = bucket[key];
+    if (typeof value === "string" && value)
+        return value;
+    const narratives = plan.narratives;
+    if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
+        const fallback = narratives[key];
+        if (typeof fallback === "string")
+            return fallback;
+    }
+    return "";
+}
+function sortedPhaseNames(phaseNames) {
+    return [...phaseNames].sort((a, b) => {
+        const [a0, a1, a2] = phaseSortKey(a);
+        const [b0, b1, b2] = phaseSortKey(b);
+        return a0 - b0 || a1 - b1 || a2.localeCompare(b2);
+    });
+}
+function groupByPhase(vbriefs) {
+    const insertionGroups = {};
+    const phaseDescriptions = {};
+    for (const vb of vbriefs) {
+        const plan = (vb.plan ?? {});
+        const phase = migratorField(plan, "Phase") || "Ungrouped";
+        if (!insertionGroups[phase])
+            insertionGroups[phase] = [];
+        insertionGroups[phase].push(vb);
+        if (!(phase in phaseDescriptions)) {
+            const pd = migratorField(plan, "PhaseDescription");
+            if (pd)
+                phaseDescriptions[phase] = pd;
+        }
+    }
+    const phaseGroups = {};
+    for (const name of sortedPhaseNames(Object.keys(insertionGroups))) {
+        phaseGroups[name] = insertionGroups[name] ?? [];
+    }
+    return [phaseGroups, phaseDescriptions];
+}
+function groupByTier(vbriefs) {
+    const tierGroups = {};
+    for (const vb of vbriefs) {
+        const plan = (vb.plan ?? {});
+        const tier = migratorField(plan, "Tier");
+        if (!tierGroups[tier])
+            tierGroups[tier] = [];
+        tierGroups[tier].push(vb);
+    }
+    return tierGroups;
+}
+function renderScopeItem(vbriefData) {
+    const plan = (vbriefData.plan ?? {});
+    const title = String(plan.title ?? "Untitled");
+    const status = String(plan.status ?? "");
+    const references = plan.references;
+    const issueRefs = extractIssueRefs(references);
+    const parts = [];
+    if (issueRefs.length > 0)
+        parts.push(`**${issueRefs[0]}**`);
+    parts.push(title);
+    if (status && status !== "pending")
+        parts.push(`\`[${status}]\``);
+    return [`- ${parts.join(" -- ")}`];
+}
+/** Generate ROADMAP.md content (mirrors ``scripts/roadmap_render.generate_roadmap_content``). */
+export function generateRoadmapContent(pendingDir, completedDir) {
+    const vbriefs = loadVbriefs(pendingDir);
+    const resolvedCompleted = completedDir ?? join(dirname(pendingDir), "completed");
+    const completedVbriefs = loadVbriefs(resolvedCompleted);
+    const lines = [ROADMAP_BANNER, "# Roadmap\n"];
+    if (vbriefs.length === 0 && completedVbriefs.length === 0) {
+        lines.push("No pending work items.\n");
+        return `${lines.join("\n")}\n`;
+    }
+    const hasPhaseNarratives = vbriefs.some((vb) => {
+        const plan = (vb.plan ?? {});
+        return Boolean(migratorField(plan, "Phase"));
+    });
+    if (hasPhaseNarratives) {
+        const [phaseGroups, phaseDescs] = groupByPhase(vbriefs);
+        for (const phaseName of Object.keys(phaseGroups)) {
+            const phaseVbriefs = phaseGroups[phaseName] ?? [];
+            lines.push(`## ${phaseName}\n`);
+            const desc = phaseDescs[phaseName] ?? "";
+            if (desc)
+                lines.push(`${desc}\n`);
+            const tierGroups = groupByTier(phaseVbriefs);
+            const hasTiers = Object.keys(tierGroups).some((t) => t.length > 0);
+            if (hasTiers) {
+                const untiered = tierGroups[""] ?? [];
+                const namedTiers = { ...tierGroups };
+                delete namedTiers[""];
+                for (const tierName of Object.keys(namedTiers)) {
+                    lines.push(`### ${tierName}\n`);
+                    for (const vb of namedTiers[tierName] ?? [])
+                        lines.push(...renderScopeItem(vb));
+                    lines.push("");
+                }
+                if (untiered.length > 0) {
+                    for (const vb of untiered)
+                        lines.push(...renderScopeItem(vb));
+                    lines.push("");
+                }
+            }
+            else {
+                for (const vb of phaseVbriefs)
+                    lines.push(...renderScopeItem(vb));
+                lines.push("");
+            }
+        }
+    }
+    else {
+        for (const vbrief of vbriefs) {
+            const plan = (vbrief.plan ?? {});
+            const planTitle = String(plan.title ?? "Untitled");
+            const issueRefs = extractIssueRefs(plan.references);
+            const titleParts = [`## ${planTitle}`];
+            if (issueRefs.length > 0)
+                titleParts.push(`(${issueRefs.join(", ")})`);
+            lines.push(`${titleParts.join(" ")}\n`);
+            const narratives = plan.narratives;
+            if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
+                const overview = narratives.Overview;
+                if (typeof overview === "string" && overview)
+                    lines.push(`${overview}\n`);
+            }
+            const depMap = buildEdgeMap(vbrief);
+            const phases = Array.isArray(plan.items)
+                ? plan.items.filter((p) => typeof p === "object" && p !== null && !Array.isArray(p))
+                : [];
+            const sortedPhases = topoSortItems(phases, depMap);
+            for (const phase of sortedPhases) {
+                const phaseId = String(phase.id ?? "");
+                const phaseTitle = String(phase.title ?? "Untitled Phase");
+                const phaseStatus = String(phase.status ?? "");
+                let heading = phaseId ? `### ${phaseId}: ${phaseTitle}` : `### ${phaseTitle}`;
+                if (phaseStatus)
+                    heading += ` \`[${phaseStatus}]\``;
+                lines.push(`${heading}\n`);
+                const narrative = phase.narrative;
+                if (typeof narrative === "object" && narrative !== null && !Array.isArray(narrative)) {
+                    for (const [key, val] of Object.entries(narrative)) {
+                        if (key !== "Traces" && key !== "Acceptance")
+                            lines.push(`${String(val)}\n`);
+                    }
+                }
+                const subItems = phase.subItems;
+                if (Array.isArray(subItems) && subItems.length > 0) {
+                    const subs = subItems.filter((s) => typeof s === "object" && s !== null && !Array.isArray(s));
+                    const sortedSubs = topoSortItems(subs, depMap);
+                    for (const item of sortedSubs)
+                        lines.push(...renderItem(item, depMap));
+                    lines.push("");
+                }
+            }
+            lines.push("---\n");
+        }
+    }
+    if (completedVbriefs.length > 0) {
+        lines.push("## Completed\n");
+        for (const vb of completedVbriefs)
+            lines.push(...renderScopeItem(vb));
+        lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function renderRoadmap(pendingDir, outPath, completedDir) {
+    try {
+        const content = generateRoadmapContent(pendingDir, completedDir);
+        writeFileSync(outPath, content, "utf8");
+        return [true, `✓ Rendered ROADMAP.md to ${outPath}`];
+    }
+    catch (exc) {
+        return [false, `✗ Failed to write ${outPath}: ${String(exc)}`];
+    }
+}
+export function checkDrift(pendingDir, roadmapPath) {
+    const expected = generateRoadmapContent(pendingDir);
+    if (!existsSync(roadmapPath)) {
+        const hasPending = existsSync(pendingDir) && readdirSync(pendingDir).some((n) => n.endsWith(".vbrief.json"));
+        const inferredCompleted = join(dirname(pendingDir), "completed");
+        const hasCompleted = existsSync(inferredCompleted) &&
+            readdirSync(inferredCompleted).some((n) => n.endsWith(".vbrief.json"));
+        if (!hasPending && !hasCompleted) {
+            return [true, "✓ No ROADMAP.md needed (no pending or completed vBRIEFs)"];
+        }
+        return [false, "✗ ROADMAP.md does not exist but vBRIEFs found"];
+    }
+    const actual = readFileSync(roadmapPath, "utf8");
+    if (actual === expected)
+        return [true, "✓ ROADMAP.md is up to date"];
+    return [false, "✗ ROADMAP.md has drifted from pending/ vBRIEFs -- run: task roadmap:render"];
+}
+/** CLI entry (mirrors ``scripts/roadmap_render.main``). */
+export function main(argv) {
+    const positional = argv.filter((a) => !a.startsWith("--"));
+    const pendingDir = positional[0] ?? join(process.cwd(), "vbrief", "pending");
+    const outPath = positional[1] ?? join(process.cwd(), "ROADMAP.md");
+    if (argv.includes("--check")) {
+        const [ok, msg] = checkDrift(pendingDir, outPath);
+        process.stdout.write(`${msg}\n`);
+        return ok ? 0 : 1;
+    }
+    const [ok, msg] = renderRoadmap(pendingDir, outPath);
+    process.stdout.write(`${msg}\n`);
+    return ok ? 0 : 1;
+}
+//# sourceMappingURL=roadmap-render.js.map

package/dist/render/spec-render.d.ts

@@ -0,0 +1,13 @@
+export type RenderSpecResult = readonly [boolean, string];
+export interface RenderSpecOptions {
+    readonly includeScopes?: boolean;
+}
+/** Render specification JSON to markdown (mirrors ``scripts/spec_render.render_spec``). */
+export declare function renderSpec(specPath: string, outPath: string, options?: RenderSpecOptions): RenderSpecResult;
+export declare function parseIncludeScopesFlag(argv: readonly string[]): {
+    includeScopes: boolean;
+    remaining: string[];
+};
+/** CLI entry (mirrors ``scripts/spec_render.main``). */
+export declare function main(argv: readonly string[]): number;
+//# sourceMappingURL=spec-render.d.ts.map