@deftai/directive-core 0.55.0

package/dist/integration-e2e/bootstrap-cache-module.d.ts

@@ -0,0 +1,5 @@
+import type { FetchAllReportImpl } from "../cache/fetch.js";
+import type { CacheModule } from "../triage/bootstrap/types.js";
+/** Adapt TS cache reports to the bootstrap `FetchAllReport` shape. */
+export declare function bootstrapCacheModule(cacheFetchAll: (options: Parameters<typeof import("../cache/fetch.js").cacheFetchAll>[0]) => FetchAllReportImpl): CacheModule;
+//# sourceMappingURL=bootstrap-cache-module.d.ts.map

package/dist/integration-e2e/bootstrap-cache-module.js

@@ -0,0 +1,21 @@
+/** Adapt TS cache reports to the bootstrap `FetchAllReport` shape. */
+export function bootstrapCacheModule(cacheFetchAll) {
+    return {
+        cacheFetchAll(kwargs) {
+            const report = cacheFetchAll({
+                source: kwargs.source,
+                repo: kwargs.repo,
+                batchSize: kwargs.batchSize,
+                delayMs: kwargs.delayMs,
+                cacheRoot: kwargs.cacheRoot,
+            });
+            return Promise.resolve({
+                succeeded: report.issuesWritten,
+                failed: report.issuesFailed,
+                skipped: report.alreadyFresh,
+                summaryLine: (source, repo) => report.summaryLine(source, repo),
+            });
+        },
+    };
+}
+//# sourceMappingURL=bootstrap-cache-module.js.map

package/dist/integration-e2e/helpers.d.ts

@@ -0,0 +1,28 @@
+export declare const REPO = "deftai/directive";
+export declare const SCALE_ISSUE_COUNT = 60;
+export declare function makeTempRoot(prefix: string): string;
+export declare function fakeIssue(number: number, body?: string): Record<string, unknown>;
+export declare function readAuditRecords(cacheRoot: string): Record<string, unknown>[];
+export declare function populateCacheLayout(cacheRoot: string, repo: string, issueNumbers: readonly number[]): void;
+export declare function createConsumerProject(parent: string): string;
+export declare function writeScopeVbrief(projectRoot: string, folder: string, filename: string, status?: string): string;
+export interface DispatchCall {
+    command: string;
+    projectRoot: string;
+    frameworkRoot: string;
+}
+export declare function isFrameworkSourceContext(frameworkRoot: string, projectRoot: string): boolean;
+/** Mirror ``scripts/_project_context.dispatch_task_check`` for consumer-task e2e. */
+export declare function dispatchTaskCheck(frameworkRoot: string, projectRoot: string, runner: (command: string, projectRoot: string, frameworkRoot: string) => {
+    code: number;
+}): number;
+export type RateLimitProbe = {
+    core: number;
+    graphql: number;
+} | null;
+/** Hermetic mirror of ``tests/integration/test_scm_smoke._probe_rate_limit``. */
+export declare function probeRateLimit(runGhApi: () => {
+    returncode: number;
+    stdout: string;
+}): RateLimitProbe;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/integration-e2e/helpers.js

@@ -0,0 +1,157 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach } from "vitest";
+import { restIssueListPaginated, setPaginatedLister, setSingleIssueFetcher, setSleepFn, } from "../cache/fetch.js";
+import { auditPath } from "../cache/paths.js";
+import { restIssueView } from "../scm/gh-rest.js";
+export const REPO = "deftai/directive";
+export const SCALE_ISSUE_COUNT = 60;
+const tempRoots = [];
+afterEach(() => {
+    setPaginatedLister(restIssueListPaginated);
+    setSingleIssueFetcher(restIssueView);
+    setSleepFn(() => { });
+    for (const root of tempRoots.splice(0)) {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+export function makeTempRoot(prefix) {
+    const root = mkdtempSync(join(tmpdir(), prefix));
+    tempRoots.push(root);
+    return root;
+}
+export function fakeIssue(number, body) {
+    return {
+        number,
+        title: `Fake issue ${number}`,
+        body: body ??
+            `## Summary\n\nEnd-to-end integration fixture for issue ${number}.\nNo credentials, no injection-heading tokens, no invisible Unicode.\n`,
+        state: "open",
+        user: { login: "tester" },
+        created_at: "2026-05-01T00:00:00Z",
+        updated_at: "2026-05-05T00:00:00Z",
+        labels: [{ name: "triage" }],
+        comments: 0,
+        html_url: `https://github.com/${REPO}/issues/${number}`,
+    };
+}
+export function readAuditRecords(cacheRoot) {
+    const audit = auditPath(cacheRoot);
+    try {
+        const raw = readFileSync(audit, "utf8");
+        return raw
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+export function populateCacheLayout(cacheRoot, repo, issueNumbers) {
+    const [owner, name] = repo.split("/", 2);
+    const base = join(cacheRoot, "github-issue", owner ?? "", name ?? "");
+    mkdirSync(base, { recursive: true });
+    for (const n of issueNumbers) {
+        const edir = join(base, String(n));
+        mkdirSync(edir, { recursive: true });
+        const payload = fakeIssue(n);
+        writeFileSync(join(edir, "raw.json"), JSON.stringify(payload), "utf8");
+        writeFileSync(join(edir, "meta.json"), JSON.stringify({
+            source: "github-issue",
+            key: `${repo}/${n}`,
+            fetched_at: "2026-05-05T00:00:00Z",
+            ttl_seconds: 7 * 24 * 60 * 60,
+            expires_at: "2099-01-01T00:00:00Z",
+            scan_result: {
+                passed: true,
+                scanned_at: "2026-05-05T00:00:00Z",
+                scanner_version: "2.1.0",
+                flags: [],
+            },
+            size_bytes: JSON.stringify(payload).length,
+            stale: false,
+        }), "utf8");
+    }
+}
+export function createConsumerProject(parent) {
+    const root = join(parent, "consumer");
+    mkdirSync(join(root, "vbrief", "proposed"), { recursive: true });
+    mkdirSync(join(root, "vbrief", "pending"), { recursive: true });
+    mkdirSync(join(root, "vbrief", "active"), { recursive: true });
+    mkdirSync(join(root, "vbrief", "completed"), { recursive: true });
+    mkdirSync(join(root, "vbrief", "cancelled"), { recursive: true });
+    writeFileSync(join(root, "vbrief", "specification.vbrief.json"), `${JSON.stringify({
+        vBRIEFInfo: { version: "0.5" },
+        plan: {
+            title: "Consumer Project",
+            status: "draft",
+            narratives: {
+                Overview: "A fixture consumer project used by deft's consumer-tasks integration suite.",
+            },
+            items: [],
+        },
+    }, null, 2)}\n`, "utf8");
+    return root;
+}
+export function writeScopeVbrief(projectRoot, folder, filename, status = "proposed") {
+    const target = join(projectRoot, "vbrief", folder, filename);
+    writeFileSync(target, `${JSON.stringify({
+        vBRIEFInfo: { version: "0.5" },
+        plan: {
+            title: "Consumer fixture scope",
+            status,
+            items: [],
+            references: [{ type: "github-issue", id: "#42" }],
+        },
+    }, null, 2)}\n`, "utf8");
+    return target;
+}
+export function isFrameworkSourceContext(frameworkRoot, projectRoot) {
+    return resolve(frameworkRoot) === resolve(projectRoot);
+}
+/** Mirror ``scripts/_project_context.dispatch_task_check`` for consumer-task e2e. */
+export function dispatchTaskCheck(frameworkRoot, projectRoot, runner) {
+    const target = isFrameworkSourceContext(frameworkRoot, projectRoot)
+        ? "check:framework-source"
+        : "check:consumer";
+    return runner(target, projectRoot, frameworkRoot).code;
+}
+/** Hermetic mirror of ``tests/integration/test_scm_smoke._probe_rate_limit``. */
+export function probeRateLimit(runGhApi) {
+    try {
+        const proc = runGhApi();
+        if (proc.returncode !== 0 || proc.stdout.trim().length === 0) {
+            return null;
+        }
+        const body = JSON.parse(proc.stdout);
+        if (typeof body !== "object" || body === null) {
+            return null;
+        }
+        const resources = body.resources;
+        if (typeof resources !== "object" || resources === null) {
+            return null;
+        }
+        const core = resources.core;
+        const graphql = resources.graphql;
+        if (typeof core !== "object" ||
+            core === null ||
+            Array.isArray(core) ||
+            typeof graphql !== "object" ||
+            graphql === null ||
+            Array.isArray(graphql)) {
+            return null;
+        }
+        const coreRemaining = Number.parseInt(String(core.remaining ?? 0), 10);
+        const graphqlRemaining = Number.parseInt(String(graphql.remaining ?? 0), 10);
+        if (Number.isNaN(coreRemaining) || Number.isNaN(graphqlRemaining)) {
+            return null;
+        }
+        return { core: coreRemaining, graphql: graphqlRemaining };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=helpers.js.map

package/dist/lifecycle/event-detect.d.ts

@@ -0,0 +1,32 @@
+/** Sentinel used by SKILL.md redirect stubs. */
+export declare const DEPRECATED_SKILL_REDIRECT_SENTINEL = "<!-- deft:deprecated-skill-redirect -->";
+export declare class EventEmissionError extends Error {
+    constructor(message: string);
+}
+/** Reset the in-process registry cache. Used by tests. */
+export declare function clearRegistryCache(): void;
+/** Return the parsed event registry. Cached after first call. */
+export declare function loadRegistry(registryPath?: string): Record<string, unknown>;
+/** Return the set of canonical event names in the registry. */
+export declare function registeredEventNames(registryPath?: string): Set<string>;
+/** UTC ISO-8601 timestamp at seconds precision. */
+export declare function nowUtcIso(): string;
+export interface EventRecord {
+    readonly event: string;
+    readonly detected_at: string;
+    readonly payload: Record<string, unknown>;
+}
+/** Build a uniform event record and optionally append it to a log file. */
+export declare function emit(name: string, payload?: Record<string, unknown> | null, options?: {
+    registryPath?: string;
+    logPathEnv?: string;
+}): EventRecord;
+/** Return an agents-md:stale payload if AGENTS.md references stale paths. */
+export declare function detectAgentsMdStale(projectRoot: string, options?: {
+    frameworkRoot?: string;
+}): Record<string, string | string[]> | null;
+/** Build a framework:remote-drift payload from a probe result. */
+export declare function detectRemoteDrift(projectRoot: string, options?: {
+    probeResult?: Record<string, unknown> | null;
+}): Record<string, unknown> | null;
+//# sourceMappingURL=event-detect.d.ts.map

package/dist/lifecycle/event-detect.js

@@ -0,0 +1,172 @@
+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";
+import { findSkillPathsInText } from "../text/redos-safe.js";
+/** Sentinel used by SKILL.md redirect stubs. */
+export const DEPRECATED_SKILL_REDIRECT_SENTINEL = "<!-- deft:deprecated-skill-redirect -->";
+const SKILL_SENTINEL_WINDOW = 200;
+const MAX_PAYLOAD_LIST_LEN = 50;
+let registryCache = 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");
+}
+export class EventEmissionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EventEmissionError";
+    }
+}
+/** Reset the in-process registry cache. Used by tests. */
+export function clearRegistryCache() {
+    registryCache = null;
+}
+/** Return the parsed event registry. Cached after first call. */
+export function loadRegistry(registryPath) {
+    const path = registryPath ?? defaultRegistryPath();
+    if (registryPath === undefined && registryCache !== null) {
+        return registryCache;
+    }
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    if (registryPath === undefined) {
+        registryCache = data;
+    }
+    return data;
+}
+/** Return the set of canonical event names in the registry. */
+export function registeredEventNames(registryPath) {
+    const registry = loadRegistry(registryPath);
+    const events = registry.events;
+    if (!Array.isArray(events)) {
+        return new Set();
+    }
+    const names = new Set();
+    for (const evt of events) {
+        if (typeof evt === "object" && evt !== null && !Array.isArray(evt)) {
+            const name = evt.name;
+            if (typeof name === "string") {
+                names.add(name);
+            }
+        }
+    }
+    return names;
+}
+/** UTC ISO-8601 timestamp at seconds precision. */
+export function nowUtcIso() {
+    const iso = new Date().toISOString();
+    return `${iso.slice(0, 19)}Z`;
+}
+function coercePayload(payload) {
+    const coerced = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (Array.isArray(value) && value.length > MAX_PAYLOAD_LIST_LEN) {
+            coerced[key] = value.slice(0, MAX_PAYLOAD_LIST_LEN);
+        }
+        else {
+            coerced[key] = value;
+        }
+    }
+    return coerced;
+}
+/** Build a uniform event record and optionally append it to a log file. */
+export function emit(name, payload = null, options = {}) {
+    const registryPath = options.registryPath;
+    const logPathEnv = options.logPathEnv ?? "DEFT_EVENT_LOG";
+    const body = payload ?? {};
+    if (!registeredEventNames(registryPath).has(name)) {
+        throw new EventEmissionError(`Event '${name}' is not registered in events/registry.json. Add it to the registry before emitting.`);
+    }
+    const record = {
+        event: name,
+        detected_at: nowUtcIso(),
+        payload: coercePayload(body),
+    };
+    const logTarget = process.env[logPathEnv];
+    if (logTarget !== undefined && logTarget.length > 0) {
+        try {
+            const logPath = resolve(logTarget);
+            mkdirSync(dirname(logPath), { recursive: true });
+            appendFileSync(logPath, `${JSON.stringify(record)}\n`, "utf8");
+        }
+        catch {
+            // Swallow log-write failures.
+        }
+    }
+    return record;
+}
+/** Return an agents-md:stale payload if AGENTS.md references stale paths. */
+export function detectAgentsMdStale(projectRoot, options = {}) {
+    const agentsMd = join(resolve(projectRoot), "AGENTS.md");
+    if (!existsSync(agentsMd)) {
+        return null;
+    }
+    let content;
+    try {
+        content = readFileSync(agentsMd, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const framework = options.frameworkRoot !== undefined
+        ? resolve(options.frameworkRoot)
+        : join(resolve(projectRoot), "deft");
+    const missingPaths = [];
+    const redirectPaths = [];
+    const seen = new Set();
+    for (const token of findSkillPathsInText(content)) {
+        if (seen.has(token)) {
+            continue;
+        }
+        seen.add(token);
+        const parts = token.split("/");
+        const slug = parts[2];
+        if (slug === undefined) {
+            continue;
+        }
+        // #1875: skills are shippable content (content/skills/ in source, flattened
+        // to skills/ in a consumer deposit).
+        const candidate = join(contentRoot(framework), "skills", slug, "SKILL.md");
+        if (!existsSync(candidate)) {
+            missingPaths.push(token);
+            continue;
+        }
+        try {
+            const head = readFileSync(candidate, "utf8").slice(0, SKILL_SENTINEL_WINDOW);
+            if (head.includes(DEPRECATED_SKILL_REDIRECT_SENTINEL)) {
+                redirectPaths.push(token);
+            }
+        }
+        catch {
+            missingPaths.push(token);
+        }
+    }
+    if (missingPaths.length === 0 && redirectPaths.length === 0) {
+        return null;
+    }
+    return {
+        agents_md_path: resolve(agentsMd),
+        missing_paths: missingPaths,
+        redirect_paths: redirectPaths,
+    };
+}
+/** Build a framework:remote-drift payload from a probe result. */
+export function detectRemoteDrift(projectRoot, options = {}) {
+    const probeResult = options.probeResult ?? null;
+    if (probeResult === null) {
+        return null;
+    }
+    if (probeResult.status !== "behind") {
+        return null;
+    }
+    return {
+        commits_behind: probeResult.commits_behind ?? null,
+        current_version: probeResult.current,
+        project_root: resolve(projectRoot),
+        remote_version: probeResult.remote,
+        upstream_url: probeResult.upstream_url ?? "",
+    };
+}
+//# sourceMappingURL=event-detect.js.map

package/dist/lifecycle/events.d.ts

@@ -0,0 +1,45 @@
+/** Default event log location (project-local). */
+export declare const DEFAULT_EVENT_LOG: string;
+/** Reset the in-process registry cache. Used by tests. */
+export declare function clearRegistryCache(): void;
+declare class LazyKnownEvents {
+    private resolved;
+    has(item: unknown): boolean;
+    [Symbol.iterator](): Iterator<string>;
+    get size(): number;
+    equals(other: unknown): boolean;
+}
+declare class LazyRequiredPayload {
+    private resolved;
+    has(item: unknown): boolean;
+    get(key: string): readonly string[];
+    entries(): [string, readonly string[]][];
+    keys(): string[];
+    values(): readonly (readonly string[])[];
+    get size(): number;
+}
+/** Lazy proxy for behavioral event names from the unified registry. */
+export declare const KNOWN_EVENTS: LazyKnownEvents;
+/** Lazy proxy for per-event required payload fields. */
+export declare const REQUIRED_PAYLOAD: LazyRequiredPayload;
+export interface BehavioralEventRecord {
+    readonly event: string;
+    readonly id: string;
+    readonly detected_at: string;
+    readonly payload: Record<string, unknown>;
+}
+/** Append a behavioral event record to the JSONL log and return it. */
+export declare function emit(name: string, payload: Record<string, unknown>, options?: {
+    logPath?: string | null;
+    detectedAt?: string | null;
+}): BehavioralEventRecord;
+/** Return all events from the log in emission order. */
+export declare function readEvents(logPath?: string | null): BehavioralEventRecord[];
+/** Return orphan session:resumed records. */
+export declare function validatePairing(events?: readonly BehavioralEventRecord[] | null, options?: {
+    logPath?: string | null;
+}): BehavioralEventRecord[];
+/** CLI entrypoint mirroring scripts/_events.py. */
+export declare function main(argv?: readonly string[]): number;
+export {};
+//# sourceMappingURL=events.d.ts.map