@deftai/directive-core 0.55.0

package/dist/lifecycle/events.js

@@ -0,0 +1,340 @@
+import { randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { contentRoot } from "../content-root.js";
+/** Default event log location (project-local). */
+export const DEFAULT_EVENT_LOG = join(".deft-cache", "events.jsonl");
+const BEHAVIORAL_CATEGORY = "behavioral";
+const REQUIRED_BEHAVIORAL_PAYLOAD = {
+    "session:interrupted": ["session_id", "reason"],
+    "session:resumed": ["session_id", "interrupted_id"],
+    "plan:approved": ["plan_ref", "approver"],
+    "legacy:detected": ["title", "source", "range", "size_bytes"],
+};
+let behavioralRegistryCache = null;
+function defaultRegistryPath() {
+    const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+    // #1875: the event registry is shippable content (content/events/ in source,
+    // flattened to events/ in a consumer deposit).
+    return join(contentRoot(repoRoot), "events", "registry.json");
+}
+function loadBehavioralRegistry() {
+    if (behavioralRegistryCache !== null) {
+        return behavioralRegistryCache;
+    }
+    const data = JSON.parse(readFileSync(defaultRegistryPath(), "utf8"));
+    const events = data.events;
+    const behavioralNames = new Set();
+    if (Array.isArray(events)) {
+        for (const event of events) {
+            if (typeof event === "object" &&
+                event !== null &&
+                !Array.isArray(event) &&
+                event.category === BEHAVIORAL_CATEGORY) {
+                const name = event.name;
+                if (typeof name === "string") {
+                    behavioralNames.add(name);
+                }
+            }
+        }
+    }
+    behavioralRegistryCache = {
+        names: behavioralNames,
+        required: REQUIRED_BEHAVIORAL_PAYLOAD,
+    };
+    return behavioralRegistryCache;
+}
+function registeredBehavioralNames() {
+    return loadBehavioralRegistry().names;
+}
+function requiredPayloadMap() {
+    return loadBehavioralRegistry().required;
+}
+/** Reset the in-process registry cache. Used by tests. */
+export function clearRegistryCache() {
+    behavioralRegistryCache = null;
+}
+class LazyKnownEvents {
+    resolved() {
+        return registeredBehavioralNames();
+    }
+    has(item) {
+        return this.resolved().has(item);
+    }
+    [Symbol.iterator]() {
+        return this.resolved()[Symbol.iterator]();
+    }
+    get size() {
+        return this.resolved().size;
+    }
+    equals(other) {
+        if (!(other instanceof Set) && !(other instanceof LazyKnownEvents)) {
+            return false;
+        }
+        const left = [...this.resolved()].sort();
+        const right = other instanceof LazyKnownEvents ? [...other.resolved()].sort() : [...other].sort();
+        return left.length === right.length && left.every((v, i) => v === right[i]);
+    }
+}
+class LazyRequiredPayload {
+    resolved() {
+        return requiredPayloadMap();
+    }
+    has(item) {
+        if (typeof item !== "string") {
+            return false;
+        }
+        return Object.hasOwn(this.resolved(), item);
+    }
+    get(key) {
+        return this.resolved()[key] ?? [];
+    }
+    entries() {
+        return Object.entries(this.resolved());
+    }
+    keys() {
+        return Object.keys(this.resolved());
+    }
+    values() {
+        return Object.values(this.resolved());
+    }
+    get size() {
+        return Object.keys(this.resolved()).length;
+    }
+}
+/** Lazy proxy for behavioral event names from the unified registry. */
+export const KNOWN_EVENTS = new LazyKnownEvents();
+/** Lazy proxy for per-event required payload fields. */
+export const REQUIRED_PAYLOAD = new LazyRequiredPayload();
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    if (value !== null && typeof value === "object") {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortKeysDeep(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function jsonStringifySorted(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+function resolveLogPath(logPath) {
+    if (logPath !== undefined && logPath !== null) {
+        return resolve(logPath);
+    }
+    const envPath = process.env.DEFT_EVENT_LOG;
+    if (envPath !== undefined && envPath.length > 0) {
+        return resolve(envPath);
+    }
+    return resolve(DEFAULT_EVENT_LOG);
+}
+function newEventId() {
+    const wallNs = BigInt(Date.now()) * 1000000n;
+    return `${wallNs}-${randomBytes(4).toString("hex")}`;
+}
+/** Append a behavioral event record to the JSONL log and return it. */
+export function emit(name, payload, options = {}) {
+    const behavioralNames = registeredBehavioralNames();
+    if (!behavioralNames.has(name)) {
+        throw new Error(`unknown event '${name}'; expected one of ${[...behavioralNames]
+            .sort()
+            .map((n) => `'${n}'`)
+            .join(", ")}`);
+    }
+    const required = requiredPayloadMap()[name] ?? [];
+    const missing = required.filter((key) => !(key in payload));
+    if (missing.length > 0) {
+        throw new Error(`event '${name}' payload missing required fields: ${JSON.stringify(missing)}`);
+    }
+    const iso = new Date().toISOString();
+    const record = {
+        event: name,
+        id: newEventId(),
+        detected_at: options.detectedAt ?? `${iso.slice(0, 19)}Z`,
+        payload: { ...payload },
+    };
+    const target = resolveLogPath(options.logPath);
+    mkdirSync(dirname(target), { recursive: true });
+    appendFileSync(target, `${jsonStringifySorted(record)}\n`, "utf8");
+    return record;
+}
+/** Return all events from the log in emission order. */
+export function readEvents(logPath) {
+    const target = resolveLogPath(logPath);
+    if (!existsSync(target)) {
+        return [];
+    }
+    const out = [];
+    const text = readFileSync(target, "utf8");
+    for (const line of text.split(/\r?\n/)) {
+        const stripped = line.trim();
+        if (stripped.length === 0) {
+            continue;
+        }
+        try {
+            out.push(JSON.parse(stripped));
+        }
+        catch { }
+    }
+    return out;
+}
+/** Return orphan session:resumed records. */
+export function validatePairing(events, options = {}) {
+    const stream = events ?? readEvents(options.logPath);
+    const openInterrupts = new Set();
+    const orphans = [];
+    for (const record of stream) {
+        if (record.event === "session:interrupted") {
+            if (typeof record.id === "string") {
+                openInterrupts.add(record.id);
+            }
+        }
+        else if (record.event === "session:resumed") {
+            const ref = record.payload?.interrupted_id;
+            if (typeof ref === "string" && openInterrupts.has(ref)) {
+                openInterrupts.delete(ref);
+            }
+            else {
+                orphans.push(record);
+            }
+        }
+    }
+    return orphans;
+}
+function parseBooleanFlag(value) {
+    return ["1", "true", "yes"].includes(value.toLowerCase());
+}
+function parseEmitArgs(args) {
+    const payload = {};
+    let name;
+    let log;
+    let i = 0;
+    if (args.length > 0 && !args[0]?.startsWith("--")) {
+        name = args[0];
+        i = 1;
+    }
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "--payload") {
+            const raw = args[i + 1];
+            if (raw === undefined) {
+                throw new Error("--payload requires a value");
+            }
+            const data = JSON.parse(raw);
+            if (typeof data !== "object" || data === null || Array.isArray(data)) {
+                throw new Error("--payload must be a JSON object");
+            }
+            Object.assign(payload, data);
+            i += 2;
+            continue;
+        }
+        if (arg === "--log") {
+            log = args[i + 1];
+            i += 2;
+            continue;
+        }
+        const flagMap = {
+            "--session-id": "session_id",
+            "--reason": "reason",
+            "--interrupted-id": "interrupted_id",
+            "--plan-ref": "plan_ref",
+            "--approver": "approver",
+            "--approval-phrase": "approval_phrase",
+            "--detail": "detail",
+            "--title": "title",
+            "--source": "source",
+            "--range": "range",
+            "--sidecar": "sidecar",
+        };
+        if (arg === "--pr-number") {
+            payload.pr_number = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 2;
+            continue;
+        }
+        if (arg === "--size-bytes") {
+            payload.size_bytes = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 2;
+            continue;
+        }
+        if (arg === "--inline") {
+            payload.inline = parseBooleanFlag(args[i + 1] ?? "");
+            i += 2;
+            continue;
+        }
+        if (arg === "--flagged") {
+            payload.flagged = parseBooleanFlag(args[i + 1] ?? "");
+            i += 2;
+            continue;
+        }
+        const field = flagMap[arg ?? ""];
+        if (field !== undefined) {
+            payload[field] = args[i + 1];
+            i += 2;
+            continue;
+        }
+        throw new Error(`unrecognized arguments: ${arg}`);
+    }
+    return { name, payload, log };
+}
+/** CLI entrypoint mirroring scripts/_events.py. */
+export function main(argv = process.argv.slice(2)) {
+    if (argv.length === 0) {
+        process.stderr.write("usage: events emit|list|validate-pairing ...\n");
+        return 2;
+    }
+    const cmd = argv[0];
+    const rest = argv.slice(1);
+    if (cmd === "emit") {
+        try {
+            const parsed = parseEmitArgs(rest);
+            if (parsed.name === undefined) {
+                process.stderr.write("emit failed: event name required\n");
+                return 2;
+            }
+            const record = emit(parsed.name, parsed.payload, { logPath: parsed.log ?? null });
+            process.stdout.write(`${JSON.stringify(record)}\n`);
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`emit failed: ${message}\n`);
+            return 2;
+        }
+    }
+    if (cmd === "list") {
+        let log;
+        for (let i = 0; i < rest.length; i += 1) {
+            if (rest[i] === "--log") {
+                log = rest[i + 1];
+            }
+        }
+        for (const record of readEvents(log ?? null)) {
+            process.stdout.write(`${jsonStringifySorted(record)}\n`);
+        }
+        return 0;
+    }
+    if (cmd === "validate-pairing") {
+        let log;
+        for (let i = 0; i < rest.length; i += 1) {
+            if (rest[i] === "--log") {
+                log = rest[i + 1];
+            }
+        }
+        const orphans = validatePairing(null, { logPath: log ?? null });
+        if (orphans.length > 0) {
+            const ids = orphans.map((r) => r.id);
+            process.stderr.write(`orphan session:resumed records (${orphans.length}): ${JSON.stringify(ids)}\n`);
+            return 1;
+        }
+        process.stdout.write("ok\n");
+        return 0;
+    }
+    process.stderr.write("usage: events emit|list|validate-pairing ...\n");
+    return 2;
+}
+//# sourceMappingURL=events.js.map

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,4 @@
+export * as eventDetect from "./event-detect.js";
+export * as events from "./events.js";
+export * as lifecycleHygiene from "./lifecycle-hygiene.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.js

@@ -0,0 +1,4 @@
+export * as eventDetect from "./event-detect.js";
+export * as events from "./events.js";
+export * as lifecycleHygiene from "./lifecycle-hygiene.js";
+//# sourceMappingURL=index.js.map

package/dist/lifecycle/lifecycle-hygiene.d.ts

@@ -0,0 +1,59 @@
+/** Default dormancy (days) past which a partially-completed epic is stranded. */
+export declare const EPIC_STRANDED_DAYS_DEFAULT = 30;
+/** Default dormancy (days) past which an undecomposed epic is stale. */
+export declare const EPIC_STALENESS_DAYS_DEFAULT = 14;
+/** vBRIEF plan.metadata.kind values treated as epic-like parents. */
+export declare const PARENT_KINDS: Set<string>;
+/** Lifecycle folders scanned for epics + children (filesystem-truth view). */
+export declare const LIFECYCLE_FOLDERS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+/** plan.status values that make an epic terminal. */
+export declare const TERMINAL_STATUSES: Set<string>;
+/** Child reference type that marks an epic as decomposed. */
+export declare const CHILD_REF_TYPE = "x-vbrief/plan";
+/** Durable tech-debt acceptance ledger relative path segments. */
+export declare const TECH_DEBT_LEDGER_RELPATH: readonly ["vbrief", ".audit", "epic-tech-debt-accepted.jsonl"];
+/** Session-start nudge tiers (rate-of-harm ranking). */
+export declare const TIER_STRANDED = 1;
+export declare const TIER_STALE_EPIC = 2;
+export declare const TIER_CAPACITY_COLDSTART = 3;
+/** Stable nudge id for the singleton capacity cold-start nudge. */
+export declare const CAPACITY_COLDSTART_NUDGE_ID = "capacity-coldstart";
+/** Default actor recorded in the tech-debt ledger. */
+export declare const DEFAULT_ACTOR = "lifecycle-hygiene";
+export interface EpicThresholds {
+    readonly strandedDays: number;
+    readonly stalenessDays: number;
+}
+export interface LifecycleNudge {
+    readonly nudgeId: string;
+    readonly kind: string;
+    readonly tier: number;
+    readonly title: string;
+    readonly epicRelPath: string;
+    readonly dormantDays: number;
+    readonly completedChildren: number;
+    readonly totalChildren: number;
+    readonly magnitude: number;
+    readonly message: string;
+}
+/** Resolve epicStrandedDays / epicStalenessDays from PROJECT-DEFINITION. */
+export declare function resolveEpicThresholds(projectRoot: string): EpicThresholds;
+/** Absolute path to vbrief/.audit/epic-tech-debt-accepted.jsonl. */
+export declare function techDebtLedgerPath(projectRoot: string): string;
+/** Append a tech-debt acceptance record and stop re-nudging the epic. */
+export declare function recordTechDebtAcceptance(projectRoot: string, epic: string, options: {
+    followUpRef: string;
+    actor?: string;
+    now?: Date;
+}): string;
+/** Return the set of epic basenames already accepted as tech-debt. */
+export declare function loadAcceptedDebtKeys(projectRoot: string): Set<string>;
+/** Detect stranded-slice (Tier 1) + stale-epic (Tier 2) nudges. */
+export declare function detectLifecycleNudges(projectRoot: string, options?: {
+    now?: Date;
+}): LifecycleNudge[];
+/** Capacity classification cold-start (Tier 3) nudge (#1606). */
+export declare function detectCapacityColdstartNudge(projectRoot: string, options?: {
+    now?: Date;
+}): LifecycleNudge | null;
+//# sourceMappingURL=lifecycle-hygiene.d.ts.map