@deftai/directive-core 0.55.0

package/dist/cache/fetch.js

@@ -0,0 +1,413 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { GhRestError, InvalidRepoError, restIssueView, runGhApi, } from "../scm/gh-rest.js";
+import { DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS } from "./constants.js";
+import { CacheError, CacheFetchError } from "./errors.js";
+import { pythonJsonLine } from "./json.js";
+import { cachePut, isFresh, validateRepo } from "./operations.js";
+import { entryDir } from "./paths.js";
+export const REST_MAX_PER_PAGE = 100;
+export const REST_PAGINATION_MAX_PAGES = 100;
+export const DEFAULT_RETRY_AFTER_FALLBACK_S = 60;
+export const PROGRESS_EVERY_N = 50;
+const RATE_LIMIT_RE = /(?:HTTP\s*429|API rate limit exceeded|rate limit exceeded)/i;
+const RETRY_AFTER_RE = /Retry-After:\s*(\d+)/i;
+let paginatedListerImpl = restIssueListPaginated;
+let sleepImpl = () => { };
+let progressWriterImpl = (line) => process.stderr.write(line);
+let progressFlusherImpl = () => { };
+let singleIssueFetcherImpl = restIssueView;
+export function setSingleIssueFetcher(fn) {
+    singleIssueFetcherImpl = fn;
+}
+export function setPaginatedLister(fn) {
+    paginatedListerImpl = fn;
+}
+export function setSleepFn(fn) {
+    sleepImpl = fn;
+}
+export function setProgressWriter(fn, flusher) {
+    progressWriterImpl = fn;
+    progressFlusherImpl = flusher ?? (() => { });
+}
+export function detectRateLimit(stderr) {
+    if (!stderr || !RATE_LIMIT_RE.test(stderr)) {
+        return [false, DEFAULT_RETRY_AFTER_FALLBACK_S];
+    }
+    const m = RETRY_AFTER_RE.exec(stderr);
+    if (m?.[1]) {
+        const n = Number.parseInt(m[1], 10);
+        if (!Number.isNaN(n))
+            return [true, n];
+    }
+    return [true, DEFAULT_RETRY_AFTER_FALLBACK_S];
+}
+function execListPage(repo, page, options) {
+    const parts = repo.split("/");
+    const owner = parts[0] ?? "";
+    const name = parts[1] ?? "";
+    const endpoint = `repos/${owner}/${name}/issues`;
+    const args = [endpoint, "--method", "GET", "--raw-field", `state=${options.state}`];
+    args.push("--raw-field", `per_page=${options.perPage}`);
+    args.push("--raw-field", `page=${page}`);
+    if (options.labels.length > 0) {
+        args.push("--raw-field", `labels=${options.labels.join(",")}`);
+    }
+    if (options.author) {
+        args.push("--raw-field", `creator=${options.author}`);
+    }
+    const runner = options.runGhApiFn ?? runGhApi;
+    const result = runner(args);
+    if (result.returncode !== 0) {
+        throw new GhRestError({
+            stderr: result.stderr.trim(),
+            exitCode: result.returncode,
+            endpoint,
+            payload: null,
+        });
+    }
+    const stdout = result.stdout.trim();
+    if (!stdout)
+        return [];
+    const parsed = JSON.parse(stdout);
+    if (!Array.isArray(parsed)) {
+        throw new GhRestError({
+            stderr: `unexpected top-level type ${typeof parsed}`,
+            exitCode: 0,
+            endpoint,
+            payload: null,
+            hint: "REST endpoint returned non-list; expected list",
+        });
+    }
+    return parsed;
+}
+export function restIssueListPaginated(repo, options = {}) {
+    const cappedPerPage = Math.min(Math.max(1, options.perPage ?? REST_MAX_PER_PAGE), REST_MAX_PER_PAGE);
+    const state = options.state ?? "open";
+    const labels = options.labels ?? [];
+    const author = options.author ?? null;
+    const excludePulls = options.excludePulls ?? true;
+    const limit = options.limit;
+    const out = [];
+    for (let page = 1; page <= REST_PAGINATION_MAX_PAGES; page += 1) {
+        const pagePayload = execListPage(repo, page, {
+            state,
+            labels,
+            author,
+            perPage: cappedPerPage,
+            runGhApiFn: options.runGhApiFn,
+        });
+        if (pagePayload.length === 0)
+            return out;
+        for (const item of pagePayload) {
+            if (excludePulls && "pull_request" in item)
+                continue;
+            out.push(item);
+            if (limit !== undefined && out.length >= limit)
+                return out.slice(0, limit);
+        }
+        if (pagePayload.length < cappedPerPage)
+            return out;
+    }
+    throw new GhRestError({
+        stderr: `pagination exceeded REST_PAGINATION_MAX_PAGES=${REST_PAGINATION_MAX_PAGES}`,
+        exitCode: 0,
+        endpoint: `repos/${repo}/issues`,
+        payload: null,
+        hint: "pass an explicit `limit` to bound the run",
+    });
+}
+function normaliseRestIssue(raw) {
+    const out = { ...raw };
+    const state = out.state;
+    if (typeof state === "string")
+        out.state = state.toLowerCase();
+    return out;
+}
+export class FetchAllReportImpl {
+    issuesWritten = 0;
+    alreadyFresh = 0;
+    issuesFailed = 0;
+    failures = [];
+    toJson() {
+        return pythonJsonLine({
+            already_fresh: this.alreadyFresh,
+            failed: this.issuesFailed,
+            failures: this.failures,
+            issues_failed: this.issuesFailed,
+            issues_written: this.issuesWritten,
+            skipped: this.alreadyFresh,
+            succeeded: this.issuesWritten,
+        });
+    }
+    summaryLine(source, repo) {
+        return (`cache:fetch-all source=${source} repo=${repo} ` +
+            `issues_written=${this.issuesWritten} ` +
+            `already_fresh=${this.alreadyFresh} ` +
+            `issues_failed=${this.issuesFailed}`);
+    }
+}
+function maybeSleep(delayMs) {
+    if (delayMs > 0)
+        sleepImpl(delayMs / 1000);
+}
+function emitFetchProgress(repo, phase, processed, total, report) {
+    const line = phase === "enumerated"
+        ? `cache:fetch-all progress repo=${repo} enumerated=${total} issues; writing cache entries...\n`
+        : `cache:fetch-all progress repo=${repo} processed=${processed}/${total} ` +
+            `issues_written=${report.issuesWritten} already_fresh=${report.alreadyFresh} ` +
+            `issues_failed=${report.issuesFailed}\n`;
+    try {
+        progressWriterImpl(line);
+        progressFlusherImpl();
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function listIssuesRest(repo, options) {
+    const filterOpts = {
+        state: options.state,
+        limit: options.limit,
+    };
+    if (options.labels.length > 0)
+        filterOpts.labels = options.labels;
+    if (options.author !== null)
+        filterOpts.author = options.author;
+    try {
+        return paginatedListerImpl(repo, filterOpts);
+    }
+    catch (err) {
+        if (err instanceof InvalidRepoError) {
+            throw new CacheFetchError(`invalid --repo '${repo}' for REST list enumeration: ${err.message}`);
+        }
+        if (err instanceof GhRestError) {
+            const [is429, retryAfter] = detectRateLimit(String(err) || err.stderr || "");
+            if (!is429) {
+                throw new CacheFetchError(`rest_issue_list_paginated failed for repo=${repo}: ${err.message}`);
+            }
+            progressWriterImpl(`cache:fetch-all rate-limited on enumeration (${repo}); sleeping ${retryAfter}s before retry\n`);
+            sleepImpl(retryAfter);
+            try {
+                return paginatedListerImpl(repo, filterOpts);
+            }
+            catch (err2) {
+                throw new CacheFetchError(`rest_issue_list_paginated failed twice for repo=${repo}: ${err2 instanceof Error ? err2.message : String(err2)}`);
+            }
+        }
+        throw err;
+    }
+}
+export function runFetchAll(options) {
+    const issues = listIssuesRest(options.repo, {
+        state: options.state ?? "open",
+        limit: options.limit ?? 1000,
+        labels: options.labels ?? [],
+        author: options.author ?? null,
+    });
+    const report = new FetchAllReportImpl();
+    const total = issues.length;
+    const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    const source = options.source;
+    const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    const delayMs = options.delayMs ?? DEFAULT_DELAY_MS;
+    const ttlSeconds = options.ttlSeconds;
+    const isFreshFn = options.isFresh ?? ((metaPath) => isFresh(metaPath));
+    const doPutFn = options.doPut ??
+        ((key, raw) => {
+            cachePut(source, key, raw, { ttlSeconds, cacheRoot });
+        });
+    if (total >= PROGRESS_EVERY_N) {
+        emitFetchProgress(options.repo, "enumerated", 0, total, report);
+    }
+    for (let i = 0; i < issues.length; i += 1) {
+        const processed = i + 1;
+        const raw = normaliseRestIssue(issues[i] ?? {});
+        const number = raw.number;
+        if (typeof number !== "number" || number <= 0) {
+            report.issuesFailed += 1;
+            report.failures.push({
+                key: `${options.repo}/?`,
+                reason: `invalid 'number' field: ${JSON.stringify(number)}`,
+            });
+        }
+        else {
+            const key = `${options.repo}/${number}`;
+            const edir = entryDir(source, key, cacheRoot);
+            if (isFreshFn(join(edir, "meta.json"))) {
+                report.alreadyFresh += 1;
+            }
+            else {
+                try {
+                    doPutFn(key, raw);
+                    report.issuesWritten += 1;
+                }
+                catch (exc) {
+                    report.issuesFailed += 1;
+                    report.failures.push({
+                        key,
+                        reason: exc instanceof Error ? exc.message : String(exc),
+                    });
+                }
+            }
+        }
+        if (total >= PROGRESS_EVERY_N && (processed % PROGRESS_EVERY_N === 0 || processed === total)) {
+            emitFetchProgress(options.repo, "writing", processed, total, report);
+        }
+        maybeSleep(delayMs);
+        if (processed % batchSize === 0)
+            maybeSleep(delayMs);
+    }
+    return report;
+}
+export function cacheFetchAll(options) {
+    if (options.source !== "github-issue") {
+        throw new CacheError(`cache:fetch-all source='${options.source}' not supported in v1 (supports: github-issue only; other sources deferred to v2)`);
+    }
+    validateRepo(options.repo);
+    const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    const delayMs = options.delayMs ?? DEFAULT_DELAY_MS;
+    if (batchSize < 1) {
+        throw new CacheError(`--batch-size must be >= 1 (got ${JSON.stringify(batchSize)})`);
+    }
+    if (delayMs < 0) {
+        throw new CacheError(`--delay-ms must be >= 0 (got ${JSON.stringify(delayMs)})`);
+    }
+    return runFetchAll({
+        repo: options.repo,
+        source: options.source,
+        cacheRoot: options.cacheRoot,
+        batchSize,
+        delayMs,
+        ttlSeconds: options.ttlSeconds,
+        state: options.state,
+        limit: options.limit,
+        labels: options.labels,
+        author: options.author,
+    });
+}
+export class StateRefreshReportImpl {
+    revisited = 0;
+    closedRewritten = 0;
+    stillOpen = 0;
+    refreshFailed = 0;
+    failures = [];
+    toJson() {
+        return pythonJsonLine({
+            closed_rewritten: this.closedRewritten,
+            failures: this.failures,
+            refresh_failed: this.refreshFailed,
+            revisited: this.revisited,
+            still_open: this.stillOpen,
+        });
+    }
+}
+export function listOpenIssueNumbers(repo, options = {}) {
+    const issues = listIssuesRest(repo, {
+        state: options.state ?? "open",
+        limit: options.limit ?? 1000,
+        labels: [],
+        author: null,
+    });
+    const numbers = new Set();
+    for (const issue of issues) {
+        const number = issue.number;
+        if (typeof number === "number" && number > 0)
+            numbers.add(number);
+    }
+    return numbers;
+}
+export function runStateRefresh(options) {
+    const fetcher = options.fetchSingle ?? restIssueView;
+    const report = new StateRefreshReportImpl();
+    const delayMs = options.delayMs ?? 0;
+    for (const [number] of options.cachedOpen) {
+        if (options.openNumbers.has(number))
+            continue;
+        report.revisited += 1;
+        const key = `${options.repo}/${number}`;
+        try {
+            const live = fetcher(options.repo, number);
+            const liveStateRaw = live.state;
+            const liveState = typeof liveStateRaw === "string" ? liveStateRaw.toLowerCase() : null;
+            if (liveState === "closed") {
+                try {
+                    options.doPut(key, normaliseRestIssue(live));
+                    report.closedRewritten += 1;
+                }
+                catch (exc) {
+                    report.refreshFailed += 1;
+                    report.failures.push({
+                        key,
+                        reason: `rewrite failed: ${exc instanceof Error ? exc.message : String(exc)}`,
+                    });
+                }
+            }
+            else {
+                report.stillOpen += 1;
+            }
+        }
+        catch (exc) {
+            report.refreshFailed += 1;
+            report.failures.push({
+                key,
+                reason: `fetch failed: ${exc instanceof Error ? exc.message : String(exc)}`,
+            });
+        }
+        maybeSleep(delayMs);
+    }
+    return report;
+}
+export function scanCachedOpenEntries(repo, source, cacheRoot) {
+    if (!repo.includes("/"))
+        return [];
+    const parts = repo.split("/", 2);
+    const owner = parts[0];
+    const name = parts[1];
+    if (owner === undefined || name === undefined)
+        return [];
+    const base = join(cacheRoot, source, owner, name);
+    if (!existsSync(base))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(base, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const n = Number.parseInt(entry.name, 10);
+        if (Number.isNaN(n) || n <= 0)
+            continue;
+        const rawPath = join(base, entry.name, "raw.json");
+        if (!existsSync(rawPath))
+            continue;
+        try {
+            const raw = JSON.parse(readFileSync(rawPath, "utf8"));
+            const stateRaw = raw.state;
+            const state = typeof stateRaw === "string" ? stateRaw.toLowerCase() : "";
+            if (state === "open")
+                out.push([n, raw]);
+        }
+        catch {
+            /* skip corrupt */
+        }
+    }
+    return out;
+}
+export function cacheRefreshClosed(options) {
+    const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    const cachedOpen = scanCachedOpenEntries(options.repo, options.source, cacheRoot);
+    const openNumbers = listOpenIssueNumbers(options.repo, { limit: options.limit ?? 1000 });
+    return runStateRefresh({
+        repo: options.repo,
+        openNumbers,
+        cachedOpen,
+        delayMs: options.delayMs ?? DEFAULT_DELAY_MS,
+        fetchSingle: singleIssueFetcherImpl,
+        doPut: (key, raw) => {
+            cachePut(options.source, key, raw, {
+                ttlSeconds: options.ttlSeconds,
+                cacheRoot,
+            });
+        },
+    });
+}
+//# sourceMappingURL=fetch.js.map

package/dist/cache/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./fetch.js";
+export * from "./io.js";
+export * from "./json.js";
+export { main } from "./main.js";
+export * from "./operations.js";
+export * from "./paths.js";
+export * from "./quota.js";
+export * from "./scanner.js";
+export * from "./time.js";
+export * from "./types.js";
+export * from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.js

@@ -0,0 +1,14 @@
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./fetch.js";
+export * from "./io.js";
+export * from "./json.js";
+export { main } from "./main.js";
+export * from "./operations.js";
+export * from "./paths.js";
+export * from "./quota.js";
+export * from "./scanner.js";
+export * from "./time.js";
+export * from "./types.js";
+export * from "./validate.js";
+//# sourceMappingURL=index.js.map

package/dist/cache/io.d.ts

@@ -0,0 +1,15 @@
+import { tmpdir } from "node:os";
+/** Write text via tempfile + rename (mirrors Python `_atomic_write_text`). */
+export declare function atomicWriteText(path: string, text: string): void;
+/** Append one JSON audit record (mirrors `_append_audit`). */
+export declare function appendAudit(record: Record<string, unknown>, cacheRoot: string): void;
+/** Touch mtime for LRU signal; failures swallowed. */
+export declare function touchMtime(path: string): void;
+/** Read file size in bytes. */
+export declare function fileSize(path: string): number;
+/** Remove directory tree; missing path is fine. */
+export declare function removeEntryDir(path: string): void;
+/** Best-effort temp file cleanup helper for tests. */
+export declare function mkTempName(dir: string, prefix: string): string;
+export { tmpdir };
+//# sourceMappingURL=io.d.ts.map

package/dist/cache/io.js

@@ -0,0 +1,53 @@
+import { randomBytes } from "node:crypto";
+import { appendFileSync, mkdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { pythonJsonLine } from "./json.js";
+/** Write text via tempfile + rename (mirrors Python `_atomic_write_text`). */
+export function atomicWriteText(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = join(dirname(path), `${path.split(/[/\\]/).pop() ?? "file"}.${randomBytes(4).toString("hex")}.tmp`);
+    try {
+        writeFileSync(tmp, text, { encoding: "utf8" });
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* v8 ignore next -- best-effort cleanup */
+        }
+        throw err;
+    }
+}
+/** Append one JSON audit record (mirrors `_append_audit`). */
+export function appendAudit(record, cacheRoot) {
+    const path = join(cacheRoot, "quarantine-audit.jsonl");
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${pythonJsonLine(record)}\n`, { encoding: "utf8" });
+}
+/** Touch mtime for LRU signal; failures swallowed. */
+export function touchMtime(path) {
+    try {
+        const now = new Date();
+        utimesSync(path, now, now);
+    }
+    catch {
+        /* read-only cache still serves hits */
+    }
+}
+/** Read file size in bytes. */
+export function fileSize(path) {
+    return statSync(path).size;
+}
+/** Remove directory tree; missing path is fine. */
+export function removeEntryDir(path) {
+    rmSync(path, { recursive: true, force: true });
+}
+/** Best-effort temp file cleanup helper for tests. */
+export function mkTempName(dir, prefix) {
+    return join(dir, `${prefix}.${randomBytes(4).toString("hex")}.tmp`);
+}
+export { tmpdir };
+//# sourceMappingURL=io.js.map

package/dist/cache/json.d.ts

@@ -0,0 +1,11 @@
+/** Recursively sort object keys like Python `json.dumps(..., sort_keys=True)`. */
+export declare function sortKeysDeep(value: unknown): unknown;
+/** Python ``True`` / ``False`` literals for CLI parity. */
+export declare function pythonBool(value: boolean): string;
+/** Python `json.dumps(..., indent=2, sort_keys=True, ensure_ascii=False)`. */
+export declare function pythonJsonDump(value: unknown, indent?: number): string;
+/** Python audit-line / fetch report `json.dumps(..., ensure_ascii=False, sort_keys=True)`. */
+export declare function pythonJsonLine(value: unknown): string;
+/** Python CLI `json.dumps(..., indent=2, ensure_ascii=False)` without sort_keys. */
+export declare function pythonJsonPretty(value: unknown, indent?: number): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/cache/json.js

@@ -0,0 +1,32 @@
+/** Recursively sort object keys like Python `json.dumps(..., sort_keys=True)`. */
+export function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortKeysDeep(item));
+    }
+    if (value !== null && typeof value === "object") {
+        const obj = value;
+        const sorted = {};
+        for (const key of Object.keys(obj).sort()) {
+            sorted[key] = sortKeysDeep(obj[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/** Python ``True`` / ``False`` literals for CLI parity. */
+export function pythonBool(value) {
+    return value ? "True" : "False";
+}
+/** Python `json.dumps(..., indent=2, sort_keys=True, ensure_ascii=False)`. */
+export function pythonJsonDump(value, indent = 2) {
+    return `${JSON.stringify(sortKeysDeep(value), null, indent)}\n`.slice(0, -1);
+}
+/** Python audit-line / fetch report `json.dumps(..., ensure_ascii=False, sort_keys=True)`. */
+export function pythonJsonLine(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+/** Python CLI `json.dumps(..., indent=2, ensure_ascii=False)` without sort_keys. */
+export function pythonJsonPretty(value, indent = 2) {
+    return JSON.stringify(value, null, indent);
+}
+//# sourceMappingURL=json.js.map

package/dist/cache/main.d.ts

@@ -0,0 +1,3 @@
+/** CLI entry point (mirrors `scripts/cache.py::main`). */
+export declare function main(argv: readonly string[]): number;
+//# sourceMappingURL=main.d.ts.map