@deftai/directive-core 0.55.0

package/dist/session/ritual-entrypoint.js

@@ -0,0 +1,86 @@
+import { cmdDoctor } from "../doctor/main.js";
+import { evaluate } from "../preflight-cache/evaluate.js";
+export const ENTRYPOINT_TIMEOUT_SECONDS = 300;
+export const ENTRYPOINT_TIMEOUT_EXIT_CODE = 124;
+/** Run an in-process ritual entrypoint with stdout/stderr capture. */
+export function callMain(mainFn, argv, _options = {}) {
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const prevStdout = process.stdout.write.bind(process.stdout);
+    const prevStderr = process.stderr.write.bind(process.stderr);
+    const captureWrite = (chunks) => (chunk, encoding, callback) => {
+        chunks.push(String(chunk));
+        const cb = typeof encoding === "function" ? encoding : callback;
+        if (typeof cb === "function") {
+            cb();
+        }
+        return true;
+    };
+    process.stdout.write = captureWrite(stdoutChunks);
+    process.stderr.write = captureWrite(stderrChunks);
+    try {
+        const exitCode = mainFn(argv);
+        return { code: exitCode || 0, stdout: stdoutChunks.join(""), stderr: stderrChunks.join("") };
+    }
+    catch (exc) {
+        const message = exc instanceof Error ? `${exc.name}: ${exc.message}` : String(exc);
+        const captured = stderrChunks.join("");
+        const stderr = captured ? `${captured}\n${message}` : message;
+        return { code: 2, stdout: stdoutChunks.join(""), stderr };
+    }
+    finally {
+        process.stdout.write = prevStdout;
+        process.stderr.write = prevStderr;
+    }
+}
+function parseProjectRoot(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            return argv[i + 1] ?? ".";
+        }
+        if (arg?.startsWith("--project-root=")) {
+            return arg.slice("--project-root=".length);
+        }
+    }
+    return ".";
+}
+/** CLI-shaped cache-fresh entrypoint (mirrors scripts/preflight_cache.py main). */
+export function runCacheFreshMain(argv) {
+    const projectRoot = parseProjectRoot(argv);
+    const allowMissingBootstrap = argv.includes("--allow-missing-bootstrap");
+    const quiet = argv.includes("--quiet");
+    const result = evaluate(projectRoot, { allowMissingBootstrap });
+    if (result.code === 0) {
+        if (!quiet) {
+            if (result.message.startsWith("⚠")) {
+                process.stderr.write(`${result.message}\n`);
+            }
+            else {
+                process.stdout.write(`${result.message}\n`);
+            }
+        }
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.code;
+}
+/** Default gated-tier runner: in-process doctor + cache-fresh (mirrors verify_session_ritual.py). */
+export function defaultRitualRunner(command, projectRoot) {
+    const [verb, ...rest] = command;
+    if (verb === "doctor") {
+        return callMain((argv) => cmdDoctor(argv), ["--project-root", projectRoot, ...rest]);
+    }
+    if (verb === "verify:cache-fresh") {
+        return callMain(runCacheFreshMain, [
+            "--allow-missing-bootstrap",
+            "--project-root",
+            projectRoot,
+            ...rest,
+        ]);
+    }
+    const label = verb ?? "entrypoint";
+    return { code: 2, stdout: "", stderr: `unknown session ritual command: ${label}` };
+}
+//# sourceMappingURL=ritual-entrypoint.js.map

package/dist/session/ritual-sentinel.d.ts

@@ -0,0 +1,58 @@
+export declare const SCHEMA_VERSION = 1;
+export declare const RITUAL_STATE_SCHEMA_VERSION = 1;
+export declare const SENTINEL_RELPATH: readonly [".deft", "last-session.json"];
+export declare const RITUAL_STATE_RELPATH: readonly [".deft", "ritual-state.json"];
+export declare const MIN_RESUME_AGE_MS: number;
+export declare const ACTIVE_VBRIEF_PREFIX = "vbrief/active/";
+export interface Sentinel {
+    readonly schemaVersion: number;
+    readonly deftVersion: string;
+    readonly timestamp: Date;
+    readonly lastActiveVbrief: string;
+    readonly lastBranch: string;
+}
+export interface RitualState {
+    readonly schemaVersion: number;
+    readonly sessionId: string;
+    readonly gitHead: string;
+    readonly worktreePath: string;
+    readonly startedAt: Date;
+    readonly quickSteps: Record<string, Record<string, unknown>>;
+    readonly gatedSteps: Record<string, Record<string, unknown>>;
+    readonly raw: Record<string, unknown>;
+}
+export interface RitualStepInput {
+    readonly ok: boolean;
+    readonly ts?: Date;
+    readonly deferredReason?: string | null;
+    readonly exitCode?: number | null;
+    readonly message?: string | null;
+    readonly command?: readonly string[] | null;
+}
+export declare function ritualStatePath(projectRoot: string): string;
+export declare function ritualStep(input: RitualStepInput): Record<string, unknown>;
+export declare function newRitualStatePayload(input: {
+    sessionId: string;
+    gitHead: string;
+    worktreePath: string;
+    startedAt?: Date;
+    quickSteps?: Record<string, Record<string, unknown>>;
+    gatedSteps?: Record<string, Record<string, unknown>>;
+}): Record<string, unknown>;
+export declare function readRitualState(projectRoot: string): [RitualState | null, string | null];
+export declare function writeRitualState(projectRoot: string, payload: Record<string, unknown>): string;
+export declare function recordRitualStep(projectRoot: string, input: {
+    tier: "quick" | "gated";
+    stepName: string;
+    step: Record<string, unknown>;
+}): string;
+export declare function readSentinel(projectRoot: string): Sentinel | null;
+export declare function writeSentinel(projectRoot: string, input: {
+    deftVersion: string;
+    lastActiveVbrief: string;
+    lastBranch: string;
+    now?: Date;
+}): string;
+export declare function computeResumeSignal(sentinel: Sentinel | null, now: Date, projectRoot: string): string | null;
+export declare function detectLatestActiveVbrief(projectRoot: string): string | null;
+//# sourceMappingURL=ritual-sentinel.d.ts.map

package/dist/session/ritual-sentinel.js

@@ -0,0 +1,338 @@
+import { closeSync, existsSync, fdatasyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, writeSync, } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { stableJson } from "./json.js";
+import { parseTimestamp, timestampIso } from "./time.js";
+export const SCHEMA_VERSION = 1;
+export const RITUAL_STATE_SCHEMA_VERSION = 1;
+export const SENTINEL_RELPATH = [".deft", "last-session.json"];
+export const RITUAL_STATE_RELPATH = [".deft", "ritual-state.json"];
+export const MIN_RESUME_AGE_MS = 2 * 60 * 60 * 1000;
+export const ACTIVE_VBRIEF_PREFIX = "vbrief/active/";
+export function ritualStatePath(projectRoot) {
+    return join(resolve(projectRoot), ...RITUAL_STATE_RELPATH);
+}
+function sentinelPath(projectRoot) {
+    return join(resolve(projectRoot), ...SENTINEL_RELPATH);
+}
+export function ritualStep(input) {
+    const payload = {
+        ok: input.ok,
+        ts: timestampIso(input.ts),
+    };
+    if (input.deferredReason) {
+        payload.deferred_reason = input.deferredReason;
+    }
+    if (input.exitCode !== null && input.exitCode !== undefined) {
+        payload.exit_code = input.exitCode;
+    }
+    if (input.message) {
+        payload.message = input.message;
+    }
+    if (input.command && input.command.length > 0) {
+        payload.command = input.command.map(String);
+    }
+    return payload;
+}
+export function newRitualStatePayload(input) {
+    return {
+        schemaVersion: RITUAL_STATE_SCHEMA_VERSION,
+        session_id: input.sessionId,
+        git_head: input.gitHead,
+        worktree_path: input.worktreePath,
+        started_at: timestampIso(input.startedAt),
+        quick_steps: input.quickSteps ?? {},
+        gated_steps: input.gatedSteps ?? {},
+    };
+}
+function validateSteps(raw, key) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return [null, `${key} must be an object`];
+    }
+    const steps = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (typeof name !== "string" || name.length === 0) {
+            return [null, `${key} contains a non-string step name`];
+        }
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            return [null, `${key}.${name} must be an object`];
+        }
+        const step = value;
+        if (typeof step.ok !== "boolean") {
+            return [null, `${key}.${name}.ok must be a boolean`];
+        }
+        if (parseTimestamp(step.ts) === null) {
+            return [null, `${key}.${name}.ts must be an ISO-8601 timestamp`];
+        }
+        const deferred = step.deferred_reason;
+        if (deferred !== undefined && deferred !== null && typeof deferred !== "string") {
+            return [null, `${key}.${name}.deferred_reason must be a string`];
+        }
+        const exitCode = step.exit_code;
+        if (exitCode !== undefined &&
+            exitCode !== null &&
+            (typeof exitCode !== "number" || !Number.isInteger(exitCode))) {
+            return [null, `${key}.${name}.exit_code must be an integer`];
+        }
+        const message = step.message;
+        if (message !== undefined && message !== null && typeof message !== "string") {
+            return [null, `${key}.${name}.message must be a string`];
+        }
+        const command = step.command;
+        if (command !== undefined &&
+            command !== null &&
+            (!Array.isArray(command) || !command.every((part) => typeof part === "string"))) {
+            return [null, `${key}.${name}.command must be an array of strings`];
+        }
+        steps[name] = { ...step };
+    }
+    return [steps, null];
+}
+function atomicWriteJson(targetPath, payload, prefix) {
+    mkdirSync(join(targetPath, ".."), { recursive: true });
+    const dir = join(targetPath, "..");
+    const tmpName = join(dir, `${prefix}${process.pid}.json.tmp`);
+    const fd = openSync(tmpName, "w");
+    try {
+        const text = `${stableJson(payload, 2)}\n`;
+        writeSync(fd, text, undefined, "utf8");
+        try {
+            fdatasyncSync(fd);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmpName, targetPath);
+}
+export function readRitualState(projectRoot) {
+    const stateFile = ritualStatePath(projectRoot);
+    try {
+        if (!existsSync(stateFile)) {
+            return [null, `ritual state missing at ${stateFile}`];
+        }
+    }
+    catch (exc) {
+        return [null, `ritual state unreadable at ${stateFile}: ${String(exc)}`];
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(stateFile, { encoding: "utf8" }));
+    }
+    catch (exc) {
+        if (exc instanceof SyntaxError) {
+            return [null, `ritual state is not valid JSON: ${exc.message}`];
+        }
+        return [null, `ritual state cannot be read: ${String(exc)}`];
+    }
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        return [null, "ritual state top-level value must be an object"];
+    }
+    const obj = payload;
+    if (obj.schemaVersion !== RITUAL_STATE_SCHEMA_VERSION) {
+        return [
+            null,
+            `ritual state schemaVersion mismatch (got ${String(obj.schemaVersion)}, want ${RITUAL_STATE_SCHEMA_VERSION})`,
+        ];
+    }
+    const sessionId = obj.session_id;
+    const gitHead = obj.git_head;
+    const worktreePathValue = obj.worktree_path;
+    const startedAt = parseTimestamp(obj.started_at);
+    for (const [fieldName, value] of [
+        ["session_id", sessionId],
+        ["git_head", gitHead],
+        ["worktree_path", worktreePathValue],
+    ]) {
+        if (typeof value !== "string" || value.length === 0) {
+            return [null, `ritual state ${fieldName} must be a non-empty string`];
+        }
+    }
+    if (startedAt === null) {
+        return [null, "ritual state started_at must be an ISO-8601 timestamp"];
+    }
+    const [quickSteps, quickErr] = validateSteps(obj.quick_steps, "quick_steps");
+    if (quickErr !== null || quickSteps === null) {
+        return [null, quickErr ?? "quick_steps invalid"];
+    }
+    const [gatedSteps, gatedErr] = validateSteps(obj.gated_steps, "gated_steps");
+    if (gatedErr !== null || gatedSteps === null) {
+        return [null, gatedErr ?? "gated_steps invalid"];
+    }
+    return [
+        {
+            schemaVersion: RITUAL_STATE_SCHEMA_VERSION,
+            sessionId: sessionId,
+            gitHead: gitHead,
+            worktreePath: worktreePathValue,
+            startedAt,
+            quickSteps,
+            gatedSteps,
+            raw: { ...obj },
+        },
+        null,
+    ];
+}
+export function writeRitualState(projectRoot, payload) {
+    const stateFile = ritualStatePath(projectRoot);
+    atomicWriteJson(stateFile, payload, ".ritual-state.");
+    return stateFile;
+}
+export function recordRitualStep(projectRoot, input) {
+    const [state, err] = readRitualState(projectRoot);
+    if (state === null) {
+        throw new Error(err ?? "ritual state missing");
+    }
+    if (input.tier !== "quick" && input.tier !== "gated") {
+        throw new Error(`tier must be 'quick' or 'gated', got ${JSON.stringify(input.tier)}`);
+    }
+    const payload = { ...state.raw };
+    const key = input.tier === "quick" ? "quick_steps" : "gated_steps";
+    const steps = { ...payload[key] };
+    steps[input.stepName] = input.step;
+    payload[key] = steps;
+    return writeRitualState(projectRoot, payload);
+}
+export function readSentinel(projectRoot) {
+    const sentinelFile = sentinelPath(projectRoot);
+    try {
+        if (!existsSync(sentinelFile)) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(sentinelFile, { encoding: "utf8" }));
+    }
+    catch {
+        return null;
+    }
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        return null;
+    }
+    const obj = payload;
+    if (obj.schemaVersion !== SCHEMA_VERSION) {
+        return null;
+    }
+    const timestamp = parseTimestamp(obj.timestamp);
+    if (timestamp === null) {
+        return null;
+    }
+    const lastActiveVbrief = obj.lastActiveVbrief;
+    const lastBranch = obj.lastBranch;
+    if (typeof lastActiveVbrief !== "string" || lastActiveVbrief.length === 0) {
+        return null;
+    }
+    if (typeof lastBranch !== "string" || lastBranch.length === 0) {
+        return null;
+    }
+    const deftVersionRaw = obj.deftVersion;
+    const deftVersion = typeof deftVersionRaw === "string" ? deftVersionRaw : "";
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        deftVersion,
+        timestamp,
+        lastActiveVbrief,
+        lastBranch,
+    };
+}
+export function writeSentinel(projectRoot, input) {
+    const sentinelFile = sentinelPath(projectRoot);
+    const instant = input.now ?? new Date();
+    const payload = {
+        schemaVersion: SCHEMA_VERSION,
+        deftVersion: input.deftVersion,
+        timestamp: timestampIso(instant),
+        lastActiveVbrief: input.lastActiveVbrief.replace(/\\/g, "/"),
+        lastBranch: input.lastBranch,
+    };
+    atomicWriteJson(sentinelFile, payload, ".last-session.");
+    return sentinelFile;
+}
+function formatElapsed(deltaMs) {
+    const totalSeconds = Math.floor(deltaMs / 1000);
+    if (totalSeconds < 3600) {
+        const minutes = Math.max(Math.floor(totalSeconds / 60), 1);
+        return `${minutes}m`;
+    }
+    const hours = Math.floor(totalSeconds / 3600);
+    return `${hours}h`;
+}
+export function computeResumeSignal(sentinel, now, projectRoot) {
+    if (sentinel === null) {
+        return null;
+    }
+    const lastActive = sentinel.lastActiveVbrief.replace(/\\/g, "/");
+    if (!lastActive.startsWith(ACTIVE_VBRIEF_PREFIX)) {
+        return null;
+    }
+    const elapsedMs = now.getTime() - sentinel.timestamp.getTime();
+    if (elapsedMs < MIN_RESUME_AGE_MS) {
+        return null;
+    }
+    const vbriefPath = join(resolve(projectRoot), lastActive);
+    try {
+        if (!statSync(vbriefPath).isFile()) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    const elapsedLabel = formatElapsed(elapsedMs);
+    return (`[deft] Last session: ${lastActive} (branch: ${sentinel.lastBranch}), ` +
+        `${elapsedLabel} ago. Resume? Run \`task vbrief:show ${lastActive}\`.`);
+}
+export function detectLatestActiveVbrief(projectRoot) {
+    const activeDir = join(resolve(projectRoot), "vbrief", "active");
+    try {
+        if (!existsSync(activeDir)) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    let children;
+    try {
+        children = readdirSync(activeDir);
+    }
+    catch {
+        return null;
+    }
+    const candidates = [];
+    for (const name of children) {
+        if (!name.endsWith(".vbrief.json")) {
+            continue;
+        }
+        const full = join(activeDir, name);
+        try {
+            const st = statSync(full);
+            if (!st.isFile()) {
+                continue;
+            }
+            candidates.push([st.mtimeMs, full]);
+        }
+        catch { }
+    }
+    if (candidates.length === 0) {
+        return null;
+    }
+    candidates.sort((a, b) => b[0] - a[0]);
+    const latest = candidates[0]?.[1];
+    if (!latest) {
+        return null;
+    }
+    try {
+        return relative(resolve(projectRoot), latest).replace(/\\/g, "/");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=ritual-sentinel.js.map

package/dist/session/session-start-hook.d.ts

@@ -0,0 +1,14 @@
+import { writeSentinel } from "./ritual-sentinel.js";
+export interface SessionStartHookOptions {
+    readonly resolveVersionFn?: () => string;
+    readonly detectBranchFn?: (projectRoot: string) => string | null;
+    readonly detectLatestActiveVbriefFn?: (projectRoot: string) => string | null;
+    readonly writeSentinelFn?: typeof writeSentinel;
+}
+/** Write ``.deft/last-session.json`` from current git state (#1269). */
+export declare function runSessionStartHookWrite(projectRoot: string, options?: SessionStartHookOptions): {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+//# sourceMappingURL=session-start-hook.d.ts.map

package/dist/session/session-start-hook.js

@@ -0,0 +1,53 @@
+import { resolveVersion } from "../doctor/paths.js";
+import { detectBranch } from "./git.js";
+import { detectLatestActiveVbrief, writeSentinel } from "./ritual-sentinel.js";
+/** Write ``.deft/last-session.json`` from current git state (#1269). */
+export function runSessionStartHookWrite(projectRoot, options = {}) {
+    const detectBranchFn = options.detectBranchFn ?? detectBranch;
+    const detectVbriefFn = options.detectLatestActiveVbriefFn ?? detectLatestActiveVbrief;
+    const resolveVersionFn = options.resolveVersionFn ?? resolveVersion;
+    const writeFn = options.writeSentinelFn ?? writeSentinel;
+    const branch = detectBranchFn(projectRoot);
+    if (!branch) {
+        return {
+            code: 2,
+            stdout: "",
+            stderr: "_session_start_hook.py: could not determine current git branch; skipping sentinel write.\n",
+        };
+    }
+    const lastActive = detectVbriefFn(projectRoot);
+    if (!lastActive) {
+        return {
+            code: 2,
+            stdout: "",
+            stderr: "_session_start_hook.py: no active vBRIEF found under vbrief/active/; skipping sentinel write.\n",
+        };
+    }
+    let deftVersion;
+    try {
+        deftVersion = resolveVersionFn();
+    }
+    catch (exc) {
+        return {
+            code: 2,
+            stdout: "",
+            stderr: `_session_start_hook.py: resolve_version failed: ${String(exc)}; skipping sentinel write.\n`,
+        };
+    }
+    try {
+        const sentinelPath = writeFn(projectRoot, {
+            deftVersion,
+            lastActiveVbrief: lastActive,
+            lastBranch: branch,
+        });
+        return { code: 0, stdout: `${sentinelPath}\n`, stderr: "" };
+    }
+    catch (exc) {
+        return {
+            code: 1,
+            stdout: "",
+            stderr: `_session_start_hook.py: sentinel write failed: ${String(exc)}\n`,
+        };
+    }
+}
+//# sourceMappingURL=session-start-hook.js.map

package/dist/session/session-start.d.ts

@@ -0,0 +1,41 @@
+import type { GitRunner } from "./git.js";
+import { ritualStatePath } from "./ritual-sentinel.js";
+export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome"];
+export declare const GATED_STEPS: readonly ["doctor", "cache_fresh"];
+export interface DefaultBranchSync {
+    readonly branch: string | null;
+    readonly upstream: string | null;
+    readonly ahead: number | null;
+    readonly behind: number | null;
+    readonly warning: string | null;
+}
+export interface SessionStartResult {
+    readonly code: number;
+    readonly payload: Record<string, unknown>;
+    readonly lines: readonly string[];
+}
+export interface SessionStartOptions {
+    readonly deferrals?: Readonly<Record<string, string>>;
+    readonly now?: Date;
+    readonly writeHistory?: boolean;
+    readonly runGit?: GitRunner;
+    readonly newSessionId?: () => string;
+    readonly runTriageWelcome?: (projectRoot: string, options: {
+        writeHistory: boolean;
+        now: Date;
+        output: (line: string) => void;
+    }) => {
+        exitCode: number;
+    };
+    readonly verifyTools?: (output: (line: string) => void) => {
+        exitCode: number;
+    };
+}
+export declare function parseDeferrals(rawValues: readonly string[]): {
+    deferrals: Record<string, string>;
+    errors: string[];
+};
+export declare function defaultBranchSync(projectRoot: string, runGit?: GitRunner): DefaultBranchSync;
+export declare function runSessionStart(projectRoot: string, options?: SessionStartOptions): SessionStartResult;
+export { ritualStatePath };
+//# sourceMappingURL=session-start.d.ts.map