@deftai/directive-core 0.55.0

package/dist/scope/main.js

@@ -0,0 +1,365 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalLogPath, readAll } from "./audit-log.js";
+import { TRANSITIONS } from "./constants.js";
+import { batchDemote, DEFAULT_OLDER_THAN_DAYS, demoteOne, resolveDemoteFilePath, resolveFilePath, resolveProjectRootStrict, } from "./demote.js";
+import { resolveProjectRoot } from "./project-context.js";
+import { recordWipCapOverride, runTransition } from "./transition.js";
+import { findByDecisionId, isAlreadyUndone, REVERSIBLE_ACTIONS, undoBatch, undoOne, } from "./undo.js";
+import { checkWipCap, formatWipCapRefusal } from "./wip-cap-check.js";
+const LIFECYCLE_USAGE_STDERR = "usage: scope_lifecycle.py [-h] [--project-root PROJECT_ROOT] [--force]\n" +
+    "                          {activate,block,cancel,complete,fail,promote,restore,unblock}\n" +
+    "                          file\n" +
+    "scope_lifecycle.py: error: the following arguments are required: action, file\n";
+function parseLifecycleArgv(argv) {
+    if (argv.length < 2) {
+        return { args: null, error: "usage" };
+    }
+    const action = argv[0] ?? "";
+    if (!(action in TRANSITIONS)) {
+        return { args: null, error: "usage" };
+    }
+    let file = "";
+    let projectRoot;
+    let force = false;
+    for (let i = 1; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined) {
+            return { args: null, error: "usage" };
+        }
+        if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--project-root") {
+            projectRoot = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (!arg.startsWith("-") && file.length === 0) {
+            file = arg;
+        }
+        else {
+            return { args: null, error: "usage" };
+        }
+    }
+    if (file.length === 0) {
+        return { args: null, error: "usage" };
+    }
+    return { args: { action, file, projectRoot, force } };
+}
+/** Main entry for scope_lifecycle.py parity. */
+export function lifecycleMain(argv) {
+    const parsed = parseLifecycleArgv(argv);
+    if (parsed.args === null) {
+        if (parsed.error === "usage") {
+            process.stderr.write(LIFECYCLE_USAGE_STDERR);
+        }
+        return 2;
+    }
+    const { action, file, projectRoot, force } = parsed.args;
+    const [filePath, error] = resolveFilePath(file, projectRoot);
+    if (error !== null || filePath === null) {
+        process.stderr.write(`Error: ${error}\n`);
+        return 2;
+    }
+    let capCheck = null;
+    if (action === "promote") {
+        const rootForCap = resolveProjectRoot(projectRoot);
+        if (rootForCap !== null) {
+            capCheck = checkWipCap(rootForCap, force === true);
+            if (!capCheck.allowed) {
+                process.stderr.write(`${formatWipCapRefusal(capCheck)}\n`);
+                return 1;
+            }
+        }
+    }
+    const result = runTransition(action, filePath);
+    if (result.ok) {
+        if (action === "promote" && capCheck !== null && capCheck.forceOverride) {
+            const rootForAudit = resolveProjectRoot(projectRoot);
+            if (rootForAudit !== null) {
+                const newPath = join(rootForAudit, "vbrief", "pending", filePath.split(/[/\\]/).pop() ?? "");
+                recordWipCapOverride(newPath, rootForAudit, capCheck);
+            }
+            process.stderr.write("\u26a0  WIP cap exceeded " +
+                `(count=${capCheck.count}, cap=${capCheck.cap}); promote allowed via --force. ` +
+                "audit: vbrief/.eval/scope-lifecycle.jsonl entry tagged wip_cap_override (#1124).\n");
+        }
+        process.stdout.write(`${result.message}\n`);
+        return 0;
+    }
+    process.stderr.write(`Error: ${result.message}\n`);
+    return 1;
+}
+function parseDemoteArgv(argv) {
+    const args = { reason: "operator-requested" };
+    let positional = "";
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined) {
+            return { args: null, error: "usage" };
+        }
+        if (arg === "--batch") {
+            args.batch = true;
+        }
+        else if (arg === "--older-than-days") {
+            args.olderThanDays = Number(argv[i + 1]);
+            i += 1;
+        }
+        else if (arg?.startsWith("--older-than-days=")) {
+            args.olderThanDays = Number(arg.slice("--older-than-days=".length));
+        }
+        else if (arg === "--reason") {
+            args.reason = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--reason=")) {
+            args.reason = arg.slice("--reason=".length);
+        }
+        else if (arg === "--project-root") {
+            args.projectRoot = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            args.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--actor") {
+            args.actor = argv[i + 1];
+            i += 1;
+        }
+        else if (!arg.startsWith("-") && positional.length === 0) {
+            positional = arg;
+        }
+        else {
+            return { args: null, error: "usage" };
+        }
+    }
+    if (args.batch === true) {
+        return { args };
+    }
+    if (positional.length === 0) {
+        return { args: null, error: "usage" };
+    }
+    args.file = positional;
+    return { args };
+}
+/** Main entry for scope_demote.py parity (included in lifecycle family). */
+export function demoteMain(argv) {
+    const parsed = parseDemoteArgv(argv);
+    if (parsed.args === null) {
+        process.stderr.write("usage: scope_demote.py <file> [--reason TEXT] [--project-root PATH]\n");
+        return 2;
+    }
+    const args = parsed.args;
+    if (args.batch === true) {
+        const [root, err] = resolveProjectRootStrict(args.projectRoot);
+        if (err !== null || root === null) {
+            process.stderr.write(`Error: ${err}\n`);
+            return 2;
+        }
+        const olderThan = args.olderThanDays ?? DEFAULT_OLDER_THAN_DAYS;
+        const [demoted, _entries, skipped] = batchDemote(root, olderThan, { actor: args.actor });
+        process.stdout.write(`Batch demote: ${demoted} demoted, ${skipped.length} skipped (older-than-days=${olderThan}).\n`);
+        for (const line of skipped) {
+            process.stdout.write(`  skipped: ${line}\n`);
+        }
+        return 0;
+    }
+    const [filePath, error] = resolveDemoteFilePath(args.file ?? "", args.projectRoot);
+    if (error !== null || filePath === null) {
+        process.stderr.write(`Error: ${error}\n`);
+        return 2;
+    }
+    const [root, rootErr] = resolveProjectRootStrict(args.projectRoot);
+    if (rootErr !== null || root === null) {
+        process.stderr.write(`Error: ${rootErr}\n`);
+        return 2;
+    }
+    const result = demoteOne(filePath, root, args.reason ?? "operator-requested", {
+        actor: args.actor,
+    });
+    if (result.ok) {
+        process.stdout.write(`${result.message}\n`);
+        return 0;
+    }
+    process.stderr.write(`Error: ${result.message}\n`);
+    return 1;
+}
+function parseUndoArgv(argv) {
+    const args = { actor: "operator" };
+    let positional = "";
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined) {
+            return { args: null, error: "usage" };
+        }
+        if (arg === "--dry-run") {
+            args.dryRun = true;
+        }
+        else if (arg === "--latest") {
+            args.latest = true;
+        }
+        else if (arg === "--decision-id") {
+            args.decisionId = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--decision-id=")) {
+            args.decisionId = arg.slice("--decision-id=".length);
+        }
+        else if (arg === "--batch-id") {
+            args.batchId = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--batch-id=")) {
+            args.batchId = arg.slice("--batch-id=".length);
+        }
+        else if (arg === "--project-root") {
+            args.projectRoot = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            args.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--actor") {
+            args.actor = argv[i + 1];
+            i += 1;
+        }
+        else if (!arg.startsWith("-") && positional.length === 0) {
+            positional = arg;
+        }
+        else {
+            return { args: null, error: "usage" };
+        }
+    }
+    if (positional.length > 0) {
+        args.decisionIdPositional = positional;
+    }
+    const decisionId = args.decisionId ?? args.decisionIdPositional;
+    if (decisionId !== undefined && args.batchId !== undefined) {
+        return {
+            args: null,
+            mutex: "Error: --decision-id (or positional <decision_id>) is mutually exclusive with --batch-id.",
+        };
+    }
+    if (args.decisionIdPositional !== undefined &&
+        args.decisionId !== undefined &&
+        args.decisionIdPositional !== args.decisionId) {
+        return {
+            args: null,
+            mutex: `Error: positional <decision_id> conflicts with --decision-id ` +
+                `('${args.decisionIdPositional}' vs '${args.decisionId}').`,
+        };
+    }
+    if (args.latest === true && (decisionId !== undefined || args.batchId !== undefined)) {
+        return {
+            args: null,
+            mutex: "Error: --latest is mutually exclusive with --decision-id, --batch-id, and the positional <decision_id>.",
+        };
+    }
+    if (decisionId === undefined && args.batchId === undefined && args.latest !== true) {
+        return {
+            args: null,
+            mutex: "Error: provide a <decision_id> (positional or --decision-id), --batch-id, or --latest.",
+        };
+    }
+    if (decisionId !== undefined) {
+        args.decisionId = decisionId;
+    }
+    return { args };
+}
+/** Main entry for scope_undo.py parity. */
+export function undoMain(argv) {
+    const parsed = parseUndoArgv(argv);
+    if (parsed.mutex !== undefined) {
+        process.stderr.write(`${parsed.mutex}\n`);
+        return 2;
+    }
+    if (parsed.args === null) {
+        process.stderr.write("usage: scope_undo.py <decision_id> [--dry-run] [--project-root PATH]\n");
+        return 2;
+    }
+    const args = parsed.args;
+    const [root, err] = resolveProjectRootStrict(args.projectRoot);
+    if (err !== null || root === null) {
+        process.stderr.write(`Error: ${err}\n`);
+        return 2;
+    }
+    const logPath = canonicalLogPath(root);
+    if (!existsSync(logPath)) {
+        process.stderr.write(`Error: audit log not found at ${logPath}. Nothing to undo.\n`);
+        return 1;
+    }
+    if (args.batchId !== undefined) {
+        const [undone, _entries, skipped, previews] = undoBatch(args.batchId, root, {
+            actor: args.actor,
+            logPath,
+            dryRun: args.dryRun,
+        });
+        if (undone === 0 && skipped.length > 0 && skipped[0]?.startsWith("No audit entries")) {
+            process.stderr.write(`${skipped[0]}\n`);
+            return 1;
+        }
+        const prefix = args.dryRun === true ? "DRY-RUN: " : "";
+        process.stdout.write(`${prefix}Batch undo: ${undone} reversed, ${skipped.length} skipped (batch_id=${args.batchId}).\n`);
+        for (const line of previews) {
+            process.stdout.write(`  preview: ${line}\n`);
+        }
+        for (const line of skipped) {
+            process.stdout.write(`  skipped: ${line}\n`);
+        }
+        return 0;
+    }
+    const logEntries = readAll(logPath);
+    let decisionId = args.decisionId;
+    if (args.latest === true) {
+        let candidate = null;
+        for (let i = logEntries.length - 1; i >= 0; i -= 1) {
+            const entry = logEntries[i];
+            if (entry === undefined) {
+                continue;
+            }
+            const action = entry.action;
+            if (typeof action !== "string" || !REVERSIBLE_ACTIONS.has(action)) {
+                continue;
+            }
+            const entryId = entry.decision_id;
+            if (typeof entryId !== "string") {
+                continue;
+            }
+            if (isAlreadyUndone(entryId, logEntries)) {
+                continue;
+            }
+            candidate = entry;
+            break;
+        }
+        if (candidate === null) {
+            process.stderr.write("Error: --latest found no reversible audit entry (demote / cancel / restore / undo) that has not already been undone.\n");
+            return 1;
+        }
+        decisionId = String(candidate.decision_id);
+        if (decisionId.length === 0) {
+            process.stderr.write("Error: --latest candidate is missing a decision_id.\n");
+            return 1;
+        }
+    }
+    const entry = findByDecisionId(decisionId ?? "", logEntries);
+    if (entry === null) {
+        process.stderr.write(`Error: no audit entry found with decision_id=${decisionId}.\n`);
+        return 1;
+    }
+    const result = undoOne(entry, root, {
+        actor: args.actor,
+        logPath,
+        dryRun: args.dryRun,
+        logEntries,
+    });
+    if (result.ok) {
+        process.stdout.write(`${result.message}\n`);
+        return 0;
+    }
+    process.stderr.write(`Error: ${result.message}\n`);
+    return 1;
+}
+//# sourceMappingURL=main.js.map

package/dist/scope/project-context.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve the consumer project root (#535).
+ * Precedence: --project-root > $DEFT_PROJECT_ROOT > sentinel walk from CWD.
+ */
+export declare function resolveProjectRoot(cliProjectRoot?: string | null, start?: string): string | null;
+//# sourceMappingURL=project-context.d.ts.map

package/dist/scope/project-context.js

@@ -0,0 +1,55 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const PROJECT_ROOT_SENTINELS = ["vbrief", ".git"];
+function isProjectRoot(candidate) {
+    return PROJECT_ROOT_SENTINELS.some((sentinel) => existsSync(join(candidate, sentinel)));
+}
+function* walkUp(start) {
+    let current = resolve(start);
+    for (;;) {
+        yield current;
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+}
+/**
+ * Resolve the consumer project root (#535).
+ * Precedence: --project-root > $DEFT_PROJECT_ROOT > sentinel walk from CWD.
+ */
+export function resolveProjectRoot(cliProjectRoot, start) {
+    if (cliProjectRoot !== undefined && cliProjectRoot !== null && cliProjectRoot.length > 0) {
+        const candidate = resolve(cliProjectRoot);
+        try {
+            if (statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            return null;
+        }
+        return null;
+    }
+    const envRoot = process.env.DEFT_PROJECT_ROOT;
+    if (envRoot !== undefined && envRoot.length > 0) {
+        const candidate = resolve(envRoot);
+        try {
+            if (statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            return null;
+        }
+        return null;
+    }
+    for (const candidate of walkUp(start ?? process.cwd())) {
+        if (isProjectRoot(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=project-context.js.map

package/dist/scope/project-definition-sync.d.ts

@@ -0,0 +1,3 @@
+/** Best-effort sync of PROJECT-DEFINITION after a lifecycle move (#1527). */
+export declare function syncProjectDefinitionAfterScopeMove(scopeData: Record<string, unknown>, oldPath: string, newPath: string, vbriefRoot: string, targetStatus: string): void;
+//# sourceMappingURL=project-definition-sync.d.ts.map

package/dist/scope/project-definition-sync.js

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { PROJECT_DEFINITION_REL_PATH } from "../policy/resolve.js";
+import { formatVbriefJson } from "./vbrief-json.js";
+import { relativeToVbrief, resolveVbriefRef, scopeIdsForFilename } from "./vbrief-ref.js";
+function rewriteProjectDefinitionPlanReference(ref, oldResolved, newRel, vbriefRoot) {
+    if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+        return false;
+    }
+    const r = ref;
+    if (r.type !== "x-vbrief/plan") {
+        return false;
+    }
+    const resolved = resolveVbriefRef(r.uri, vbriefRoot);
+    if (resolved === null || resolve(resolved) !== resolve(oldResolved)) {
+        return false;
+    }
+    const uri = r.uri;
+    const newUri = typeof uri === "string" && uri.startsWith("file://") ? `file://${newRel}` : newRel;
+    if (newUri === uri) {
+        return false;
+    }
+    r.uri = newUri;
+    return true;
+}
+function projectItemReferencesScope(item, oldResolved, newResolved, vbriefRoot) {
+    const metadata = item.metadata;
+    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
+        const meta = metadata;
+        const sourcePath = meta.source_path;
+        if (typeof sourcePath === "string") {
+            const resolved = resolveVbriefRef(sourcePath, vbriefRoot);
+            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                return true;
+            }
+        }
+        const metadataRefs = meta.references;
+        if (Array.isArray(metadataRefs)) {
+            for (const ref of metadataRefs) {
+                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, vbriefRoot);
+                if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                    return true;
+                }
+            }
+        }
+    }
+    const refs = item.references;
+    if (Array.isArray(refs)) {
+        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, vbriefRoot);
+            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function projectItemMatchesScope(item, scopeData, oldPath, newPath, vbriefRoot) {
+    const oldResolved = resolve(oldPath);
+    const newResolved = resolve(newPath);
+    if (projectItemReferencesScope(item, oldResolved, newResolved, vbriefRoot)) {
+        return true;
+    }
+    const itemId = item.id;
+    if (typeof itemId === "string" &&
+        scopeIdsForFilename(resolve(newPath).split(/[/\\]/).pop() ?? "").has(itemId)) {
+        return true;
+    }
+    const scopePlan = scopeData.plan;
+    const scopeTitle = typeof scopePlan === "object" && scopePlan !== null && !Array.isArray(scopePlan)
+        ? scopePlan.title
+        : undefined;
+    const itemTitle = item.title;
+    return (typeof scopeTitle === "string" && typeof itemTitle === "string" && itemTitle === scopeTitle);
+}
+/** Best-effort sync of PROJECT-DEFINITION after a lifecycle move (#1527). */
+export function syncProjectDefinitionAfterScopeMove(scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
+    const newRel = relativeToVbrief(newPath, vbriefRoot);
+    if (newRel === null) {
+        return;
+    }
+    const projectRoot = dirname(resolve(vbriefRoot));
+    const projectDefPath = join(projectRoot, PROJECT_DEFINITION_REL_PATH);
+    if (!existsSync(projectDefPath)) {
+        return;
+    }
+    try {
+        const projectDef = JSON.parse(readFileSync(projectDefPath, "utf8"));
+        const plan = projectDef.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            return;
+        }
+        const p = plan;
+        let changed = false;
+        const oldResolved = resolve(oldPath);
+        const refs = p.references;
+        if (Array.isArray(refs)) {
+            for (const ref of refs) {
+                if (rewriteProjectDefinitionPlanReference(ref, oldResolved, newRel, vbriefRoot)) {
+                    changed = true;
+                }
+            }
+        }
+        const items = p.items;
+        if (Array.isArray(items)) {
+            for (const item of items) {
+                if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                    continue;
+                }
+                const i = item;
+                if (!projectItemMatchesScope(i, scopeData, oldPath, newPath, vbriefRoot)) {
+                    continue;
+                }
+                if (i.status !== targetStatus) {
+                    i.status = targetStatus;
+                    changed = true;
+                }
+                let metadata = i.metadata;
+                if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+                    metadata = {};
+                    i.metadata = metadata;
+                }
+                const meta = metadata;
+                const targetFolder = dirname(resolve(newPath)).split(/[/\\]/).pop() ?? "";
+                if (meta.source_path !== newRel) {
+                    meta.source_path = newRel;
+                    changed = true;
+                }
+                if (meta.lifecycle_folder !== targetFolder) {
+                    meta.lifecycle_folder = targetFolder;
+                    changed = true;
+                }
+            }
+        }
+        if (changed) {
+            writeFileSync(projectDefPath, formatVbriefJson(projectDef), "utf8");
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+//# sourceMappingURL=project-definition-sync.js.map

package/dist/scope/transition.d.ts

@@ -0,0 +1,10 @@
+import { detectLifecycleFolder } from "./decomposed-refs.js";
+import type { WipCapCheck } from "./wip-cap-check.js";
+export interface TransitionResult {
+    readonly ok: boolean;
+    readonly message: string;
+}
+export declare function runTransition(action: string, filePath: string, now?: Date): TransitionResult;
+export declare function recordWipCapOverride(filePath: string, projectRoot: string, check: WipCapCheck, now?: Date): void;
+export { detectLifecycleFolder };
+//# sourceMappingURL=transition.d.ts.map