@deftai/directive-core 0.55.0

package/dist/scope/decomposed-refs.d.ts

@@ -0,0 +1,6 @@
+/** Sync decomposed parents' forward references after a child move (#1485). */
+export declare function updateDecomposedParentBackReferences(childData: Record<string, unknown>, oldChildPath: string, newChildPath: string, vbriefDir: string): string[];
+/** Sync decomposed children's planRefs after a parent move (#1487). */
+export declare function updateDecomposedChildBackReferences(parentData: Record<string, unknown>, oldParentPath: string, newParentPath: string, vbriefDir: string): string[];
+export declare function detectLifecycleFolder(filePath: string): string | null;
+//# sourceMappingURL=decomposed-refs.d.ts.map

package/dist/scope/decomposed-refs.js

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { formatVbriefJson } from "./vbrief-json.js";
+import { collectChildUris, collectPlanRefs, resolveVbriefRef } from "./vbrief-ref.js";
+function rewriteOnePlanRef(value, oldParentResolved, newParentRel, vbriefDir) {
+    if (typeof value !== "string" || value.length === 0) {
+        return [value, false];
+    }
+    const resolved = resolveVbriefRef(value, vbriefDir);
+    if (resolved === null || resolve(resolved) !== resolve(oldParentResolved)) {
+        return [value, false];
+    }
+    const newValue = value.startsWith("file://") ? `file://${newParentRel}` : newParentRel;
+    return [newValue, newValue !== value];
+}
+function rewriteParentChildReference(parentPath, oldChildResolved, newChildRel, vbriefDir) {
+    let parentData;
+    try {
+        parentData = JSON.parse(readFileSync(parentPath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    const parentPlan = parentData.plan;
+    if (typeof parentPlan !== "object" || parentPlan === null || Array.isArray(parentPlan)) {
+        return false;
+    }
+    const plan = parentPlan;
+    const refs = plan.references;
+    if (!Array.isArray(refs)) {
+        return false;
+    }
+    let changed = false;
+    for (const ref of refs) {
+        if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+            continue;
+        }
+        const r = ref;
+        if (r.type !== "x-vbrief/plan") {
+            continue;
+        }
+        const resolved = resolveVbriefRef(r.uri, vbriefDir);
+        if (resolved === null || resolve(resolved) !== resolve(oldChildResolved)) {
+            continue;
+        }
+        const uri = r.uri;
+        const newUri = typeof uri === "string" && uri.startsWith("file://") ? `file://${newChildRel}` : newChildRel;
+        if (newUri !== uri) {
+            r.uri = newUri;
+            changed = true;
+        }
+    }
+    if (changed) {
+        try {
+            writeFileSync(parentPath, formatVbriefJson(parentData), "utf8");
+        }
+        catch {
+            return false;
+        }
+    }
+    return changed;
+}
+/** Sync decomposed parents' forward references after a child move (#1485). */
+export function updateDecomposedParentBackReferences(childData, oldChildPath, newChildPath, vbriefDir) {
+    const plan = childData.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return [];
+    }
+    const oldResolved = resolve(oldChildPath);
+    let newRel;
+    try {
+        newRel = relative(resolve(vbriefDir), resolve(newChildPath)).replace(/\\/g, "/");
+    }
+    catch {
+        return [];
+    }
+    const updated = [];
+    const seen = new Set();
+    for (const planRef of collectPlanRefs(plan)) {
+        const parentPath = resolveVbriefRef(planRef, vbriefDir);
+        if (parentPath === null || seen.has(parentPath)) {
+            continue;
+        }
+        seen.add(parentPath);
+        if (!existsSync(parentPath)) {
+            continue;
+        }
+        if (rewriteParentChildReference(parentPath, oldResolved, newRel, vbriefDir)) {
+            updated.push(parentPath);
+        }
+    }
+    return updated;
+}
+function rewriteChildParentReference(childPath, oldParentResolved, newParentRel, vbriefDir) {
+    let childData;
+    try {
+        childData = JSON.parse(readFileSync(childPath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    const childPlan = childData.plan;
+    if (typeof childPlan !== "object" || childPlan === null || Array.isArray(childPlan)) {
+        return false;
+    }
+    const plan = childPlan;
+    let changed = false;
+    const [newRoot, rootChanged] = rewriteOnePlanRef(plan.planRef, oldParentResolved, newParentRel, vbriefDir);
+    if (rootChanged) {
+        plan.planRef = newRoot;
+        changed = true;
+    }
+    const items = plan.items;
+    if (Array.isArray(items)) {
+        for (const item of items) {
+            if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                continue;
+            }
+            const i = item;
+            const [newItem, itemChanged] = rewriteOnePlanRef(i.planRef, oldParentResolved, newParentRel, vbriefDir);
+            if (itemChanged) {
+                i.planRef = newItem;
+                changed = true;
+            }
+        }
+    }
+    if (changed) {
+        try {
+            writeFileSync(childPath, formatVbriefJson(childData), "utf8");
+        }
+        catch {
+            return false;
+        }
+    }
+    return changed;
+}
+/** Sync decomposed children's planRefs after a parent move (#1487). */
+export function updateDecomposedChildBackReferences(parentData, oldParentPath, newParentPath, vbriefDir) {
+    const plan = parentData.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return [];
+    }
+    const oldResolved = resolve(oldParentPath);
+    let newRel;
+    try {
+        newRel = relative(resolve(vbriefDir), resolve(newParentPath)).replace(/\\/g, "/");
+    }
+    catch {
+        return [];
+    }
+    const updated = [];
+    const seen = new Set();
+    for (const childUri of collectChildUris(plan)) {
+        const childPath = resolveVbriefRef(childUri, vbriefDir);
+        if (childPath === null || seen.has(childPath)) {
+            continue;
+        }
+        seen.add(childPath);
+        if (!existsSync(childPath)) {
+            continue;
+        }
+        if (rewriteChildParentReference(childPath, oldResolved, newRel, vbriefDir)) {
+            updated.push(childPath);
+        }
+    }
+    return updated;
+}
+export function detectLifecycleFolder(filePath) {
+    const parentName = dirname(filePath).split(/[/\\]/).pop() ?? "";
+    const folders = new Set(["proposed", "pending", "active", "completed", "cancelled"]);
+    return folders.has(parentName) ? parentName : null;
+}
+//# sourceMappingURL=decomposed-refs.js.map

package/dist/scope/demote.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULT_OLDER_THAN_DAYS = 45;
+export declare const SOURCE_FOLDER = "pending";
+export declare const TARGET_FOLDER = "proposed";
+export declare const TARGET_STATUS = "proposed";
+export interface DemoteResult {
+    readonly ok: boolean;
+    readonly message: string;
+    readonly auditEntry: Record<string, unknown> | null;
+}
+export declare function demoteOne(filePath: string, projectRoot: string, reason: string, options?: {
+    actor?: string;
+    now?: Date;
+    logPath?: string;
+    batchId?: string;
+}): DemoteResult;
+export declare function batchDemote(projectRoot: string, olderThanDays: number, options?: {
+    actor?: string;
+    now?: Date;
+    logPath?: string;
+}): [number, Record<string, unknown>[], string[]];
+export declare function resolveFilePath(raw: string, cliProjectRoot?: string | null): [string | null, string | null];
+export declare function resolveDemoteFilePath(raw: string, cliProjectRoot?: string | null): [string | null, string | null];
+export declare function resolveProjectRootStrict(cliProjectRoot?: string | null): [string | null, string | null];
+//# sourceMappingURL=demote.d.ts.map

package/dist/scope/demote.js

@@ -0,0 +1,209 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { stripTrailingPathSeparators } from "../text/redos-safe.js";
+import { append, canonicalLogPath, latestForPath, newDecisionId } from "./audit-log.js";
+import { resolveProjectRoot } from "./project-context.js";
+import { formatVbriefJson, utcNowIso } from "./vbrief-json.js";
+import { canonicalRelpath } from "./vbrief-ref.js";
+export const DEFAULT_OLDER_THAN_DAYS = 45;
+export const SOURCE_FOLDER = "pending";
+export const TARGET_FOLDER = "proposed";
+export const TARGET_STATUS = "proposed";
+function parsePlanUpdated(text) {
+    if (text === undefined || text.length === 0) {
+        return null;
+    }
+    let candidate = text;
+    if (candidate.endsWith("Z")) {
+        candidate = `${candidate.slice(0, -1)}+00:00`;
+    }
+    const dt = new Date(candidate);
+    return Number.isNaN(dt.getTime()) ? null : dt;
+}
+function daysInPending(filePath, planUpdated, now) {
+    const parsed = parsePlanUpdated(planUpdated);
+    const stamp = parsed ?? new Date(statSync(filePath).mtimeMs);
+    const deltaMs = now.getTime() - stamp.getTime();
+    return Math.max(0, Math.floor(deltaMs / (24 * 60 * 60 * 1000)));
+}
+export function demoteOne(filePath, projectRoot, reason, options = {}) {
+    const resolved = resolve(filePath);
+    const actor = options.actor ?? "operator";
+    const now = options.now ?? new Date();
+    const logPath = options.logPath ?? canonicalLogPath(projectRoot);
+    if (!existsSync(resolved)) {
+        return { ok: false, message: `File not found: ${resolved}`, auditEntry: null };
+    }
+    const basename = resolved.split(/[/\\]/).pop() ?? "";
+    if (!basename.endsWith(".vbrief.json")) {
+        return {
+            ok: false,
+            message: `Not a vBRIEF file (expected .vbrief.json): ${basename}`,
+            auditEntry: null,
+        };
+    }
+    const parent = dirname(resolved).split(/[/\\]/).pop() ?? "";
+    if (parent !== SOURCE_FOLDER) {
+        return {
+            ok: false,
+            message: `Invalid transition: 'demote' requires file in ${SOURCE_FOLDER}/. File is in ${parent}/.`,
+            auditEntry: null,
+        };
+    }
+    let data;
+    try {
+        data = JSON.parse(readFileSync(resolved, "utf8"));
+    }
+    catch (err) {
+        return { ok: false, message: `Invalid JSON in ${resolved}: ${String(err)}`, auditEntry: null };
+    }
+    const plan = data.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return {
+            ok: false,
+            message: `Missing or invalid 'plan' object in ${resolved}`,
+            auditEntry: null,
+        };
+    }
+    const planObj = plan;
+    const planUpdatedBefore = planObj.updated;
+    const days = daysInPending(resolved, typeof planUpdatedBefore === "string" ? planUpdatedBefore : undefined, now);
+    const canonicalPath = canonicalRelpath(resolved, projectRoot);
+    const priorPromote = latestForPath(canonicalPath, "promote", logPath);
+    const originalPromotionDecisionId = priorPromote !== null ? priorPromote.decision_id : null;
+    const timestamp = utcNowIso(now);
+    planObj.status = TARGET_STATUS;
+    planObj.updated = timestamp;
+    writeFileSync(resolved, formatVbriefJson(data), "utf8");
+    const vbriefRoot = dirname(dirname(resolved));
+    const targetDir = join(vbriefRoot, TARGET_FOLDER);
+    mkdirSync(targetDir, { recursive: true });
+    const targetPath = join(targetDir, basename);
+    renameSync(resolved, targetPath);
+    const canonicalPathAfter = canonicalRelpath(targetPath, projectRoot);
+    const demoteMeta = {
+        was_promoted: parent === SOURCE_FOLDER,
+        original_promotion_decision_id: originalPromotionDecisionId,
+        days_in_pending: days,
+        demote_reason: reason,
+        demoted_from: parent,
+    };
+    if (options.batchId !== undefined) {
+        demoteMeta.batch_id = options.batchId;
+    }
+    const entry = {
+        decision_id: newDecisionId(),
+        timestamp,
+        action: "demote",
+        vbrief_path: canonicalPathAfter,
+        from_status: "pending",
+        to_status: TARGET_STATUS,
+        actor,
+        demote_meta: demoteMeta,
+    };
+    append(entry, logPath);
+    return {
+        ok: true,
+        message: `Demoted ${basename}: ${SOURCE_FOLDER}/ -> ${TARGET_FOLDER}/ ` +
+            `(status: ${TARGET_STATUS}, days_in_pending: ${days})`,
+        auditEntry: entry,
+    };
+}
+export function batchDemote(projectRoot, olderThanDays, options = {}) {
+    if (olderThanDays < 0) {
+        throw new Error(`--older-than-days must be >= 0, got ${olderThanDays}`);
+    }
+    const now = options.now ?? new Date();
+    const pendingDir = join(resolve(projectRoot), "vbrief", SOURCE_FOLDER);
+    if (!existsSync(pendingDir)) {
+        return [0, [], []];
+    }
+    const reason = `batch:older-than-days:${olderThanDays}`;
+    let batchId;
+    const auditEntries = [];
+    const skipped = [];
+    let demoted = 0;
+    const files = readdirSync(pendingDir)
+        .filter((name) => name.endsWith(".vbrief.json"))
+        .sort();
+    for (const name of files) {
+        const candidate = join(pendingDir, name);
+        let data;
+        try {
+            data = JSON.parse(readFileSync(candidate, "utf8"));
+        }
+        catch (err) {
+            skipped.push(`${name}: read error: ${String(err)}`);
+            continue;
+        }
+        const plan = data.plan;
+        const planUpdated = typeof plan === "object" && plan !== null && !Array.isArray(plan)
+            ? plan.updated
+            : undefined;
+        const days = daysInPending(candidate, typeof planUpdated === "string" ? planUpdated : undefined, now);
+        if (days < olderThanDays) {
+            skipped.push(`${name}: ${days} day(s) in pending (< ${olderThanDays})`);
+            continue;
+        }
+        if (batchId === undefined) {
+            batchId = newDecisionId();
+        }
+        const result = demoteOne(candidate, projectRoot, reason, {
+            ...options,
+            now,
+            batchId,
+        });
+        if (result.ok && result.auditEntry !== null) {
+            auditEntries.push(result.auditEntry);
+            demoted += 1;
+        }
+        else {
+            skipped.push(`${name}: ${result.message}`);
+        }
+    }
+    return [demoted, auditEntries, skipped];
+}
+export function resolveFilePath(raw, cliProjectRoot) {
+    const stripped = stripTrailingPathSeparators(raw.trim());
+    if (stripped.length === 0) {
+        return [
+            null,
+            "No vBRIEF file path provided. Usage: scope_lifecycle.py <action> <file> [--project-root PATH]",
+        ];
+    }
+    if (isAbsolute(stripped)) {
+        return [resolve(stripped), null];
+    }
+    const projectRoot = resolveProjectRoot(cliProjectRoot);
+    if (projectRoot === null) {
+        return [
+            null,
+            `Cannot resolve relative path '${stripped}': no project root detected. Pass --project-root PATH, set $DEFT_PROJECT_ROOT, or run from inside a directory tree that contains vbrief/ or .git/ (#535).`,
+        ];
+    }
+    return [resolve(join(projectRoot, stripped)), null];
+}
+export function resolveDemoteFilePath(raw, cliProjectRoot) {
+    const stripped = stripTrailingPathSeparators(raw.trim());
+    if (stripped.length === 0) {
+        return [
+            null,
+            "No vBRIEF file path provided. Usage: scope_demote.py <file> [--reason TEXT] [--project-root PATH]",
+        ];
+    }
+    if (isAbsolute(stripped)) {
+        return [resolve(stripped), null];
+    }
+    return resolveFilePath(raw, cliProjectRoot);
+}
+export function resolveProjectRootStrict(cliProjectRoot) {
+    const projectRoot = resolveProjectRoot(cliProjectRoot);
+    if (projectRoot === null) {
+        return [
+            null,
+            "Cannot determine project root. Pass --project-root PATH, set $DEFT_PROJECT_ROOT, or run from inside a directory tree that contains vbrief/ or .git/ (#535).",
+        ];
+    }
+    return [projectRoot, null];
+}
+//# sourceMappingURL=demote.js.map

package/dist/scope/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./audit-log.js";
+export * from "./constants.js";
+export * from "./decomposed-refs.js";
+export * from "./demote.js";
+export * from "./main.js";
+export * from "./project-context.js";
+export * from "./transition.js";
+export * from "./undo.js";
+export * from "./vbrief-json.js";
+export * from "./vbrief-ref.js";
+export * from "./wip-cap-check.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/scope/index.js

@@ -0,0 +1,12 @@
+export * from "./audit-log.js";
+export * from "./constants.js";
+export * from "./decomposed-refs.js";
+export * from "./demote.js";
+export * from "./main.js";
+export * from "./project-context.js";
+export * from "./transition.js";
+export * from "./undo.js";
+export * from "./vbrief-json.js";
+export * from "./vbrief-ref.js";
+export * from "./wip-cap-check.js";
+//# sourceMappingURL=index.js.map

package/dist/scope/main.d.ts

@@ -0,0 +1,30 @@
+export interface LifecycleArgs {
+    action: string;
+    file: string;
+    projectRoot?: string;
+    force?: boolean;
+}
+export interface DemoteArgs {
+    file?: string;
+    batch?: boolean;
+    olderThanDays?: number;
+    reason?: string;
+    projectRoot?: string;
+    actor?: string;
+}
+export interface UndoArgs {
+    decisionId?: string;
+    decisionIdPositional?: string;
+    batchId?: string;
+    latest?: boolean;
+    dryRun?: boolean;
+    actor?: string;
+    projectRoot?: string;
+}
+/** Main entry for scope_lifecycle.py parity. */
+export declare function lifecycleMain(argv: string[]): number;
+/** Main entry for scope_demote.py parity (included in lifecycle family). */
+export declare function demoteMain(argv: string[]): number;
+/** Main entry for scope_undo.py parity. */
+export declare function undoMain(argv: string[]): number;
+//# sourceMappingURL=main.d.ts.map