@deftai/directive-core 0.55.0

package/dist/branch/evaluate.d.ts

@@ -0,0 +1,23 @@
+import { type BranchState } from "./git.js";
+export declare const DEFAULT_BRANCHES: Set<string>;
+/** When the setup-interview is mid-flight on the default branch. */
+export declare const ENV_SETUP_EXEMPTION = "DEFT_SETUP_INTERVIEW";
+/** Result of branch-protection evaluation; mirrors Python `(exit_code, message)`. */
+export interface EvaluateResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly message: string;
+}
+export interface EvaluateOptions {
+    /** Skip live git lookup when provided (unit tests). */
+    readonly branchOverride?: BranchState;
+    /** Simulate git-not-found (unit tests). */
+    readonly gitNotFound?: boolean;
+    readonly defaultBranches?: ReadonlySet<string>;
+    readonly allowMissingProjectDefinition?: boolean;
+}
+/**
+ * Pure evaluator — returns exit code + human message. Faithful to
+ * `scripts/preflight_branch.evaluate`.
+ */
+export declare function evaluate(projectRoot: string, options?: EvaluateOptions): EvaluateResult;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/branch/evaluate.js

@@ -0,0 +1,136 @@
+import { disclosureLine } from "../policy/disclosure.js";
+import { ENV_BYPASS, resolvePolicy } from "../policy/resolve.js";
+import { currentBranch, GitNotFoundError } from "./git.js";
+export const DEFAULT_BRANCHES = new Set(["master", "main"]);
+/** When the setup-interview is mid-flight on the default branch. */
+export const ENV_SETUP_EXEMPTION = "DEFT_SETUP_INTERVIEW";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function setupExemptionActive() {
+    const raw = process.env[ENV_SETUP_EXEMPTION] ?? "";
+    return TRUTHY.has(raw.trim().toLowerCase());
+}
+function isDefaultBranch(name, defaultBranches) {
+    const lowered = name.toLowerCase();
+    for (const branch of defaultBranches) {
+        if (branch.toLowerCase() === lowered) {
+            return true;
+        }
+    }
+    return false;
+}
+function buildBlockMessage(branch, result) {
+    const parts = [
+        "❌ deft branch-protection: refusing to commit/push directly to the " +
+            `default branch '${branch}' (#747).`,
+        "",
+        `  Source: policy=${result.source}`,
+    ];
+    if (result.error !== null) {
+        parts.push(`  Error: ${result.error}`);
+    }
+    if (result.deprecationWarning !== null) {
+        parts.push(`  Note: ${result.deprecationWarning}`);
+    }
+    parts.push("", "  How to proceed:", "    • Create a feature branch:  git switch -c feat/<name>", "    • Or opt out via the typed surface:", "        task policy:allow-direct-commits -- --confirm", `    • Or set the emergency-escape env-var:  ${ENV_BYPASS}=1`, "", "  See README.md (Branch policy) and skills/deft-directive-setup/", "  Phase 2 Step 9 (capability-cost disclosure).");
+    return parts.join("\n");
+}
+/**
+ * Pure evaluator — returns exit code + human message. Faithful to
+ * `scripts/preflight_branch.evaluate`.
+ */
+export function evaluate(projectRoot, options = {}) {
+    const defaultBranches = options.defaultBranches ?? DEFAULT_BRANCHES;
+    const allowMissingProjectDefinition = options.allowMissingProjectDefinition ?? false;
+    if (setupExemptionActive()) {
+        return {
+            exitCode: 0,
+            message: "✓ deft branch-protection: setup-interview exemption active " +
+                `(${ENV_SETUP_EXEMPTION}=1) -- proceeding without policy lookup.`,
+        };
+    }
+    let branch;
+    let detached;
+    if (options.gitNotFound) {
+        const exc = new GitNotFoundError("git executable not found on PATH");
+        return {
+            exitCode: 2,
+            message: "❌ deft branch-protection: cannot determine current branch -- " +
+                `${exc.message}\n` +
+                "  Recovery: install git (https://git-scm.com/) or set DEFT_PYTHON " +
+                "so the hook can dispatch correctly.",
+        };
+    }
+    if (options.branchOverride !== undefined) {
+        branch = options.branchOverride.branch;
+        detached = options.branchOverride.detached;
+    }
+    else {
+        try {
+            const state = currentBranch(projectRoot);
+            branch = state.branch;
+            detached = state.detached;
+        }
+        catch (err) {
+            if (err instanceof GitNotFoundError) {
+                return {
+                    exitCode: 2,
+                    message: "❌ deft branch-protection: cannot determine current branch -- " +
+                        `${err.message}\n` +
+                        "  Recovery: install git (https://git-scm.com/) or set DEFT_PYTHON " +
+                        "so the hook can dispatch correctly.",
+                };
+            }
+            throw err;
+        }
+    }
+    if (detached) {
+        return {
+            exitCode: 0,
+            message: "✓ deft branch-protection: detached HEAD detected -- nothing to gate.",
+        };
+    }
+    if (!isDefaultBranch(branch, defaultBranches)) {
+        return {
+            exitCode: 0,
+            message: `✓ deft branch-protection: feature branch '${branch}' -- proceeding.`,
+        };
+    }
+    const result = resolvePolicy(projectRoot);
+    if (result.allowDirectCommits) {
+        return {
+            exitCode: 0,
+            message: `⚠ deft branch-protection: on default branch '${branch}', but ` +
+                `policy allows it (${disclosureLine(result)}).`,
+        };
+    }
+    if (result.source === "default-fail-closed" && result.error !== null) {
+        if (allowMissingProjectDefinition && result.error.includes("not found")) {
+            return {
+                exitCode: 0,
+                message: "✓ deft branch-protection: PROJECT-DEFINITION missing AND " +
+                    "--allow-missing-project-definition was passed -- treating as " +
+                    "bootstrap state (the setup interview will write the typed flag).",
+            };
+        }
+        const recovery = result.error.includes("not found")
+            ? "  Recovery: run `task setup` to create vbrief/" +
+                "PROJECT-DEFINITION.vbrief.json, OR set the env-var bypass:\n" +
+                `      ${ENV_BYPASS}=1\n` +
+                "  Or pass --allow-missing-project-definition to this script " +
+                "(setup-interview hook only)."
+            : "  Recovery: fix the malformed PROJECT-DEFINITION (e.g. ensure " +
+                "`plan.policy.allowDirectCommitsToMaster` is a boolean and " +
+                "`plan` is an object), then re-run.";
+        return {
+            exitCode: 2,
+            message: "❌ deft branch-protection: PROJECT-DEFINITION cannot be resolved.\n" +
+                `  Detail: ${result.error}\n` +
+                recovery,
+        };
+    }
+    return {
+        exitCode: 1,
+        message: buildBlockMessage(branch, result),
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/branch/git.d.ts

@@ -0,0 +1,15 @@
+/** Raised when ``git`` is not on PATH (#777 Greptile P2 fix). */
+export declare class GitNotFoundError extends Error {
+    constructor(message: string);
+}
+export interface BranchState {
+    readonly branch: string;
+    readonly detached: boolean;
+}
+/**
+ * Return current branch via `git symbolic-ref --quiet --short HEAD`.
+ * Maps to detached HEAD when symbolic-ref fails; raises GitNotFoundError when
+ * the git executable is missing.
+ */
+export declare function currentBranch(projectRoot: string): BranchState;
+//# sourceMappingURL=git.d.ts.map

package/dist/branch/git.js

@@ -0,0 +1,42 @@
+import { execFileSync } from "node:child_process";
+/** Raised when ``git`` is not on PATH (#777 Greptile P2 fix). */
+export class GitNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitNotFoundError";
+    }
+}
+/**
+ * Return current branch via `git symbolic-ref --quiet --short HEAD`.
+ * Maps to detached HEAD when symbolic-ref fails; raises GitNotFoundError when
+ * the git executable is missing.
+ */
+export function currentBranch(projectRoot) {
+    try {
+        const stdout = execFileSync("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const branch = stdout.trim();
+        if (branch.length > 0) {
+            return { branch, detached: false };
+        }
+        return { branch: "", detached: true };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            throw new GitNotFoundError("git executable not found on PATH");
+        }
+        if (typeof e.status === "number" && e.status === 127) {
+            const stderr = typeof e.stderr === "string" ? e.stderr : String(e.stderr ?? "");
+            if (stderr.includes("git executable not found")) {
+                throw new GitNotFoundError(stderr.trim() || "git executable not found on PATH");
+            }
+        }
+        // Detached HEAD (symbolic-ref exits non-zero) -- never blocked.
+        return { branch: "", detached: true };
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/branch/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./evaluate.js";
+export * from "./git.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/branch/index.js

@@ -0,0 +1,3 @@
+export * from "./evaluate.js";
+export * from "./git.js";
+//# sourceMappingURL=index.js.map

package/dist/cache/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cache/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/* v8 ignore file -- thin shebang entry; covered via main.ts tests */
+import { fileURLToPath } from "node:url";
+import { main } from "./main.js";
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(main(process.argv.slice(2)));
+}
+//# sourceMappingURL=cli.js.map

package/dist/cache/constants.d.ts

@@ -0,0 +1,12 @@
+/** Default on-disk cache root (mirrors `scripts/cache.py`). */
+export declare const DEFAULT_CACHE_ROOT = ".deft-cache";
+export declare const AUDIT_LOG_NAME = "quarantine-audit.jsonl";
+/** Hard-coded TTLs per source type (v1 ships github-issue only). */
+export declare const SOURCE_TTL_SECONDS: Readonly<Record<string, number>>;
+export declare const ALLOWED_SOURCES: readonly string[];
+export declare const GH_KEY_RE: RegExp;
+export declare const REPO_RE: RegExp;
+export declare const DEFAULT_BATCH_SIZE = 10;
+export declare const DEFAULT_DELAY_MS = 0;
+export declare const DEFAULT_PRUNE_OLDER_THAN_DAYS = 30;
+//# sourceMappingURL=constants.d.ts.map

package/dist/cache/constants.js

@@ -0,0 +1,14 @@
+/** Default on-disk cache root (mirrors `scripts/cache.py`). */
+export const DEFAULT_CACHE_ROOT = ".deft-cache";
+export const AUDIT_LOG_NAME = "quarantine-audit.jsonl";
+/** Hard-coded TTLs per source type (v1 ships github-issue only). */
+export const SOURCE_TTL_SECONDS = {
+    "github-issue": 7 * 24 * 60 * 60,
+};
+export const ALLOWED_SOURCES = Object.freeze(Object.keys(SOURCE_TTL_SECONDS));
+export const GH_KEY_RE = /^([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*)\/(\d+)$/;
+export const REPO_RE = /^([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*)$/;
+export const DEFAULT_BATCH_SIZE = 10;
+export const DEFAULT_DELAY_MS = 0;
+export const DEFAULT_PRUNE_OLDER_THAN_DAYS = 30;
+//# sourceMappingURL=constants.js.map

package/dist/cache/errors.d.ts

@@ -0,0 +1,34 @@
+/** Generic cache-layer failure (subprocess, parse, IO). */
+export declare class CacheError extends Error {
+    constructor(message: string);
+}
+/** Cache miss for the requested (source, key). */
+export declare class CacheNotFoundError extends Error {
+    constructor(message: string);
+}
+/** meta.json failed schema validation on read or write. */
+export declare class CacheValidationError extends Error {
+    constructor(message: string);
+}
+/** Raised when caps cannot be honored even after eviction (CLI exit 3). */
+export declare class CacheCapBreachedError extends Error {
+    readonly reason: string;
+    readonly maxBytes: number;
+    readonly maxEntries: number;
+    readonly currentBytes: number;
+    readonly currentEntries: number;
+    readonly incomingBytes: number;
+    constructor(options: {
+        reason: string;
+        maxBytes: number;
+        maxEntries: number;
+        currentBytes: number;
+        currentEntries: number;
+        incomingBytes: number;
+    });
+}
+/** Subprocess / parse failure during fetch-all orchestration. */
+export declare class CacheFetchError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/cache/errors.js

@@ -0,0 +1,52 @@
+/** Generic cache-layer failure (subprocess, parse, IO). */
+export class CacheError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CacheError";
+    }
+}
+/** Cache miss for the requested (source, key). */
+export class CacheNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CacheNotFoundError";
+    }
+}
+/** meta.json failed schema validation on read or write. */
+export class CacheValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CacheValidationError";
+    }
+}
+/** Raised when caps cannot be honored even after eviction (CLI exit 3). */
+export class CacheCapBreachedError extends Error {
+    reason;
+    maxBytes;
+    maxEntries;
+    currentBytes;
+    currentEntries;
+    incomingBytes;
+    constructor(options) {
+        const msg = `cache cap breached (${options.reason}): ` +
+            `max_bytes=${options.maxBytes} max_entries=${options.maxEntries} ` +
+            `current_bytes=${options.currentBytes} current_entries=${options.currentEntries} ` +
+            `incoming_bytes=${options.incomingBytes}`;
+        super(msg);
+        this.name = "CacheCapBreachedError";
+        this.reason = options.reason;
+        this.maxBytes = options.maxBytes;
+        this.maxEntries = options.maxEntries;
+        this.currentBytes = options.currentBytes;
+        this.currentEntries = options.currentEntries;
+        this.incomingBytes = options.incomingBytes;
+    }
+}
+/** Subprocess / parse failure during fetch-all orchestration. */
+export class CacheFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CacheFetchError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/cache/fetch.d.ts

@@ -0,0 +1,101 @@
+import { type RunGhApiFn } from "../scm/gh-rest.js";
+import type { FetchAllReport, StateRefreshReport } from "./types.js";
+export declare const REST_MAX_PER_PAGE = 100;
+export declare const REST_PAGINATION_MAX_PAGES = 100;
+export declare const DEFAULT_RETRY_AFTER_FALLBACK_S = 60;
+export declare const PROGRESS_EVERY_N = 50;
+export type PaginatedLister = (repo: string, options?: {
+    state?: string;
+    labels?: readonly string[];
+    author?: string | null;
+    perPage?: number;
+    limit?: number;
+    excludePulls?: boolean;
+    runGhApiFn?: RunGhApiFn;
+}) => Array<Record<string, unknown>>;
+export type SleepFn = (seconds: number) => void;
+export type ProgressWriter = (line: string) => void;
+export declare function setSingleIssueFetcher(fn: (repo: string, n: number) => Record<string, unknown>): void;
+export declare function setPaginatedLister(fn: PaginatedLister): void;
+export declare function setSleepFn(fn: SleepFn): void;
+export declare function setProgressWriter(fn: ProgressWriter, flusher?: () => void): void;
+export declare function detectRateLimit(stderr: string): [boolean, number];
+export declare function restIssueListPaginated(repo: string, options?: {
+    state?: string;
+    labels?: readonly string[];
+    author?: string | null;
+    perPage?: number;
+    limit?: number;
+    excludePulls?: boolean;
+    runGhApiFn?: RunGhApiFn;
+}): Record<string, unknown>[];
+export declare class FetchAllReportImpl implements FetchAllReport {
+    issuesWritten: number;
+    alreadyFresh: number;
+    issuesFailed: number;
+    failures: Array<{
+        key: string;
+        reason: string;
+    }>;
+    toJson(): string;
+    summaryLine(source: string, repo: string): string;
+}
+export declare function runFetchAll(options: {
+    repo: string;
+    source: string;
+    cacheRoot?: string;
+    batchSize?: number;
+    delayMs?: number;
+    ttlSeconds?: number | null;
+    state?: string;
+    limit?: number;
+    labels?: readonly string[];
+    author?: string | null;
+    isFresh?: (metaPath: string) => boolean;
+    doPut?: (key: string, raw: Record<string, unknown>) => void;
+}): FetchAllReportImpl;
+export declare function cacheFetchAll(options: {
+    source: string;
+    repo: string;
+    batchSize?: number;
+    delayMs?: number;
+    ttlSeconds?: number | null;
+    state?: string;
+    limit?: number;
+    labels?: readonly string[];
+    author?: string | null;
+    cacheRoot?: string;
+}): FetchAllReportImpl;
+export declare class StateRefreshReportImpl implements StateRefreshReport {
+    revisited: number;
+    closedRewritten: number;
+    stillOpen: number;
+    refreshFailed: number;
+    failures: Array<{
+        key: string;
+        reason: string;
+    }>;
+    toJson(): string;
+}
+export declare function listOpenIssueNumbers(repo: string, options?: {
+    state?: string;
+    limit?: number;
+}): Set<number>;
+export declare function runStateRefresh(options: {
+    repo: string;
+    openNumbers: Set<number>;
+    cachedOpen: Array<[number, Record<string, unknown>]>;
+    doPut: (key: string, raw: Record<string, unknown>) => void;
+    fetchSingle?: (repo: string, n: number) => Record<string, unknown>;
+    delayMs?: number;
+}): StateRefreshReportImpl;
+export declare function scanCachedOpenEntries(repo: string, source: string, cacheRoot: string): Array<[number, Record<string, unknown>]>;
+export declare function cacheRefreshClosed(options: {
+    source: string;
+    repo: string;
+    ttlSeconds?: number | null;
+    delayMs?: number;
+    limit?: number;
+    cacheRoot?: string;
+}): StateRefreshReportImpl;
+//# sourceMappingURL=fetch.d.ts.map