@ashlr/hub 2.2.0

package/dist/core/inbox/store.js

@@ -0,0 +1,258 @@
+/**
+ * store.ts — Proposal persistence for the M23 approval inbox.
+ *
+ * Persists one proposal per file at ~/.ashlr/inbox/<id>.json.
+ *
+ * GUARDRAILS:
+ *  - PURE PERSISTENCE: never applies anything, never mutates a repo, never
+ *    auto-advances status. Status changes happen ONLY through setStatus().
+ *  - Never throws: all exported functions swallow errors and return safe
+ *    defaults (null / [] / 0) so callers remain unblocked.
+ *  - Atomic write: write to <id>.json.tmp then rename, matching the pattern
+ *    in core/portfolio/backlog.ts.
+ *  - No secrets stored: diffs contain user-owned code (fine); tokens/keys are
+ *    not proposal fields. audit() strips secrets defensively on its side.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { audit } from '../sandbox/audit.js';
+// ---------------------------------------------------------------------------
+// Path helpers (re-resolved at call-time so tests can relocate HOME)
+// ---------------------------------------------------------------------------
+/**
+ * Absolute path to the inbox directory: ~/.ashlr/inbox.
+ * Created lazily by createProposal / setStatus — this function does NOT
+ * create it.
+ */
+export function inboxDir() {
+    return join(homedir(), '.ashlr', 'inbox');
+}
+/** Absolute path to a specific proposal file. */
+function proposalPath(id) {
+    return join(inboxDir(), `${id}.json`);
+}
+// ---------------------------------------------------------------------------
+// ID generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate a stable, readable slug id for a proposal.
+ *
+ * Format: `prop-<timestamp-ms>-<4-hex-random>`.
+ * - Timestamp prefix gives chronological sorting for free.
+ * - 4-hex suffix avoids collisions from sub-millisecond bursts.
+ * - All lowercase alphanumeric + hyphens → safe as a filename stem.
+ */
+let _seq = 0;
+function generateId() {
+    const ts = Date.now().toString(36); // base-36 ms timestamp, ~8 chars
+    const rand = Math.floor(Math.random() * 0xffff)
+        .toString(16)
+        .padStart(4, '0');
+    // Monotonic, zero-padded process counter as the final segment. createdAt has
+    // only millisecond resolution, so proposals created in the same ms would
+    // otherwise have no defined recency order. The counter gives listProposals a
+    // stable "most-recent first" tiebreaker. The counter comes BEFORE the random
+    // segment so lexicographic id comparison orders by (timestamp, monotonic counter).
+    const seq = (_seq++).toString(36).padStart(6, '0');
+    return `prop-${ts}-${seq}-${rand}`;
+}
+// ---------------------------------------------------------------------------
+// Atomic write helper
+// ---------------------------------------------------------------------------
+/** Persist a proposal atomically (tmp-write + rename, POSIX-atomic). */
+function persistProposal(proposal) {
+    const dir = inboxDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const dest = proposalPath(proposal.id);
+    const tmp = dest + '.tmp';
+    writeFileSync(tmp, JSON.stringify(proposal, null, 2) + '\n', 'utf8');
+    renameSync(tmp, dest);
+}
+// ---------------------------------------------------------------------------
+// Structural validation
+// ---------------------------------------------------------------------------
+/** Light type-guard so we never return garbage from the store. */
+function isValidProposal(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return false;
+    }
+    const p = parsed;
+    return (typeof p['id'] === 'string' &&
+        typeof p['origin'] === 'string' &&
+        typeof p['kind'] === 'string' &&
+        typeof p['title'] === 'string' &&
+        typeof p['summary'] === 'string' &&
+        typeof p['status'] === 'string' &&
+        typeof p['createdAt'] === 'string');
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Create a new proposal, persist it, audit the creation, and return it.
+ *
+ * Assigns:
+ *  - `id`        — fresh unique slug (stable, filename-safe)
+ *  - `status`    — 'pending'
+ *  - `createdAt` — current ISO timestamp
+ *
+ * NEVER applies or mutates any repo.
+ * Never throws — on persistence failure the in-memory proposal is still
+ * returned (best-effort).
+ */
+export function createProposal(p) {
+    const proposal = {
+        ...p,
+        id: generateId(),
+        status: 'pending',
+        createdAt: new Date().toISOString(),
+    };
+    try {
+        persistProposal(proposal);
+    }
+    catch {
+        // Persistence failure: caller still gets the in-memory proposal.
+    }
+    audit({
+        action: 'inbox:proposal-created',
+        repo: proposal.repo ?? null,
+        sandboxId: proposal.sandboxId ?? null,
+        summary: `proposal created: [${proposal.kind}] ${proposal.title} (id=${proposal.id})`,
+        result: 'ok',
+    });
+    return proposal;
+}
+/**
+ * List all persisted proposals, most-recent first by `createdAt`.
+ * Optionally filter by status.
+ *
+ * Read-only. Unreadable / corrupt files are silently skipped.
+ * Never throws.
+ */
+export function listProposals(filter) {
+    try {
+        const dir = inboxDir();
+        if (!existsSync(dir))
+            return [];
+        let files;
+        try {
+            files = readdirSync(dir).filter((f) => f.endsWith('.json') && !f.endsWith('.tmp'));
+        }
+        catch {
+            return [];
+        }
+        const proposals = [];
+        for (const file of files) {
+            try {
+                const raw = readFileSync(join(dir, file), 'utf8');
+                const parsed = JSON.parse(raw);
+                if (isValidProposal(parsed)) {
+                    proposals.push(parsed);
+                }
+            }
+            catch {
+                // Unreadable or malformed — skip silently.
+            }
+        }
+        // Apply optional status filter.
+        const filtered = filter?.status !== undefined
+            ? proposals.filter((p) => p.status === filter.status)
+            : proposals;
+        // Most-recent first by createdAt (ISO strings sort lexicographically).
+        // Tiebreak on id (which embeds a monotonic counter) so proposals created
+        // within the same millisecond still order newest-first deterministically.
+        filtered.sort((a, b) => {
+            if (a.createdAt < b.createdAt)
+                return 1;
+            if (a.createdAt > b.createdAt)
+                return -1;
+            if (a.id < b.id)
+                return 1;
+            if (a.id > b.id)
+                return -1;
+            return 0;
+        });
+        return filtered;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Load a single proposal by id.
+ * Returns null if absent, unreadable, or malformed.
+ * Never throws.
+ */
+export function loadProposal(id) {
+    try {
+        const p = proposalPath(id);
+        if (!existsSync(p))
+            return null;
+        const raw = readFileSync(p, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (isValidProposal(parsed))
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a new status (and optional result detail) for an existing proposal.
+ *
+ * - Sets `decidedAt` to now when moving to 'approved' or 'rejected'.
+ * - No-op if the proposal does not exist or cannot be read.
+ * - NEVER applies anything — pure persistence change only.
+ * - Audits the decision.
+ * - Never throws.
+ */
+export function setStatus(id, status, result) {
+    try {
+        const existing = loadProposal(id);
+        if (existing === null)
+            return;
+        const decidedStatuses = ['approved', 'rejected'];
+        const updated = {
+            ...existing,
+            status,
+            ...(result !== undefined ? { result } : {}),
+            ...(decidedStatuses.includes(status)
+                ? { decidedAt: new Date().toISOString() }
+                : {}),
+        };
+        try {
+            persistProposal(updated);
+        }
+        catch {
+            // Persistence failure — swallow; audit still fires.
+        }
+        audit({
+            action: `inbox:proposal-${status}`,
+            repo: updated.repo ?? null,
+            sandboxId: updated.sandboxId ?? null,
+            summary: `proposal ${status}: [${updated.kind}] ${updated.title} (id=${id})${result ? ` — ${result}` : ''}`,
+            result: 'ok',
+        });
+    }
+    catch {
+        // Never throws.
+    }
+}
+/**
+ * Count proposals with status === 'pending'.
+ * Read-only. Returns 0 on any error.
+ * Never throws.
+ */
+export function pendingCount() {
+    try {
+        return listProposals({ status: 'pending' }).length;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/core/inbox/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/core/inbox/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAE5C,8EAA8E;AAC9E,qEAAqE;AACrE,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,iDAAiD;AACjD,SAAS,YAAY,CAAC,EAAU;IAC9B,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC;AAED,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,IAAI,IAAI,GAAG,CAAC,CAAC;AACb,SAAS,UAAU;IACjB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,iCAAiC;IACrE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;SAC5C,QAAQ,CAAC,EAAE,CAAC;SACZ,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpB,6EAA6E;IAC7E,yEAAyE;IACzE,6EAA6E;IAC7E,6EAA6E;IAC7E,mFAAmF;IACnF,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACnD,OAAO,QAAQ,EAAE,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;AACrC,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,wEAAwE;AACxE,SAAS,eAAe,CAAC,QAAkB;IACzC,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,GAAG,MAAM,CAAC;IAC1B,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACrE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,kEAAkE;AAClE,SAAS,eAAe,CAAC,MAAe;IACtC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,CAAC,GAAG,MAAiC,CAAC;IAC5C,OAAO,CACL,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,QAAQ;QAC3B,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;QAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ;QAChC,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,QAAQ,CACnC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,CAAgD;IAEhD,MAAM,QAAQ,GAAa;QACzB,GAAG,CAAC;QACJ,EAAE,EAAE,UAAU,EAAE;QAChB,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,IAAI,CAAC;QACH,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;IACnE,CAAC;IAED,KAAK,CAAC;QACJ,MAAM,EAAE,wBAAwB;QAChC,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,IAAI;QAC3B,SAAS,EAAE,QAAQ,CAAC,SAAS,IAAI,IAAI;QACrC,OAAO,EAAE,sBAAsB,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,KAAK,QAAQ,QAAQ,CAAC,EAAE,GAAG;QACrF,MAAM,EAAE,IAAI;KACb,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAoC;IAChE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;QACvB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAEhC,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YACH,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACrF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,SAAS,GAAe,EAAE,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;gBAClD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBACxC,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC5B,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,2CAA2C;YAC7C,CAAC;QACH,CAAC;QAED,gCAAgC;QAChC,MAAM,QAAQ,GACZ,MAAM,EAAE,MAAM,KAAK,SAAS;YAC1B,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC;YACrD,CAAC,CAAC,SAAS,CAAC;QAEhB,uEAAuE;QACvE,yEAAyE;QACzE,0EAA0E;QAC1E,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACrB,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS;gBAAE,OAAO,CAAC,CAAC;YACxC,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS;gBAAE,OAAO,CAAC,CAAC,CAAC;YACzC,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;gBAAE,OAAO,CAAC,CAAC;YAC1B,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;gBAAE,OAAO,CAAC,CAAC,CAAC;YAC3B,OAAO,CAAC,CAAC;QACX,CAAC,CAAC,CAAC;QAEH,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QAC3B,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,GAAG,GAAG,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACpC,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,eAAe,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CACvB,EAAU,EACV,MAAsB,EACtB,MAAe;IAEf,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO;QAE9B,MAAM,eAAe,GAAqB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QACnE,MAAM,OAAO,GAAa;YACxB,GAAG,QAAQ;YACX,MAAM;YACN,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,GAAG,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAClC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE;gBACzC,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;QAEF,IAAI,CAAC;YACH,eAAe,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;QACtD,CAAC;QAED,KAAK,CAAC;YACJ,MAAM,EAAE,kBAAkB,MAAM,EAAE;YAClC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI;YAC1B,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;YACpC,OAAO,EAAE,YAAY,MAAM,MAAM,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,KAAK,QAAQ,EAAE,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;YAC3G,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,gBAAgB;IAClB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC;QACH,OAAO,aAAa,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/core/index-engine.d.ts

@@ -0,0 +1,62 @@
+/**
+ * index-engine.ts
+ *
+ * Scans cfg.roots, builds an AshlrIndex of fully-populated IndexedItems,
+ * and persists / loads the index from ~/.ashlr/index.json.
+ *
+ * Walk strategy
+ * ─────────────
+ * Each entry in cfg.roots is one of:
+ *   A) A github/<category> parent  – walk category → repo (depth ≤ 3).
+ *   B) A Desktop root              – index top-level folders + notable loose
+ *      files; do NOT descend into a dir already covered by a github root,
+ *      and do NOT descend into node_modules / .git / dist.
+ *
+ * Symlinks are detected with lstat. They are indexed once as kind:'symlink'
+ * and are never followed for further repo discovery (avoids double-counting).
+ *
+ * One bad directory must never crash the whole walk – every stat/readdir call
+ * is wrapped in a try/catch and failures are silently skipped.
+ */
+import type { AshlrConfig, AshlrIndex } from './types.js';
+/**
+ * Options for {@link buildIndex}.
+ */
+export interface BuildIndexOptions {
+    /**
+     * When provided, the builder attempts an incremental update: any repo whose
+     * directory mtime has not changed since `previousIndex.generatedAt` is
+     * reused from the previous index instead of being re-stat'd and re-git'd.
+     *
+     * Pass `undefined` (or omit the option) for a full rebuild.  The index
+     * command passes this when `--refresh` is NOT specified and a prior index
+     * already exists.
+     */
+    previousIndex?: AshlrIndex;
+}
+/**
+ * Build a fresh (or incrementally updated) AshlrIndex by scanning all cfg.roots.
+ *
+ * Walk order:
+ *  1. Treat each root that ends in `/github/<category>` as a github category root.
+ *  2. Treat every remaining root as a "desktop" root (top-level only).
+ *  3. Track seenPaths (via realpath) across all roots to avoid double-counting.
+ *
+ * Incremental mode (opts.previousIndex present):
+ *  For repos already in the previous index, compare the directory's current
+ *  mtime against `previousIndex.generatedAt`.  If the mtime is older (i.e.
+ *  the directory has not been touched since the last index was built), reuse
+ *  the prior IndexedItem directly — no stat/readdir/git calls needed.
+ *  Any repo whose mtime is >= generatedAt (or that is new) is rebuilt normally.
+ */
+export declare function buildIndex(cfg: AshlrConfig, opts?: BuildIndexOptions): AshlrIndex;
+/**
+ * Load the index from INDEX_PATH.
+ * Returns null if the file is absent, unreadable, or not valid JSON.
+ */
+export declare function loadIndex(): AshlrIndex | null;
+/**
+ * Persist the index to INDEX_PATH as pretty-printed JSON.
+ * Creates CONFIG_DIR if it does not exist.
+ */
+export declare function writeIndex(index: AshlrIndex): void;