pi-memoria 0.2.0 → 0.3.1

package/src/usage.ts

@@ -1,188 +0,0 @@
-/**
- * Retrieval and write statistics, kept in `.index/usage.json`.
- *
- * This is derived data: deleting the file loses promotion and staleness hints
- * and nothing else. The search path must never do disk I/O, so hits are counted
- * in memory and flushed on a debounce; the runtime also refreshes a note's
- * `last_used` frontmatter at most once per `lastUsedWriteIntervalMs`.
- */
-
-import { join } from "node:path";
-import { INDEX_DIR, USAGE_FILE } from "./config.ts";
-import { atomicWriteFile, readFileOrUndefined } from "./util.ts";
-import type { UsageEntry, UsageFile } from "./types.ts";
-
-export const USAGE_VERSION = 1;
-
-/** Upper bound on tracked notes; the least recently used are dropped first. */
-export const MAX_USAGE_ENTRIES = 50_000;
-
-function emptyEntry(): UsageEntry {
-	return { hits: 0, writes: 0, lastUsed: 0 };
-}
-
-function coerceEntry(raw: unknown): UsageEntry | undefined {
-	if (!raw || typeof raw !== "object") return undefined;
-	const input = raw as Record<string, unknown>;
-	const number = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0);
-	const entry = { hits: number(input.hits), writes: number(input.writes), lastUsed: number(input.lastUsed) };
-	if (entry.hits === 0 && entry.writes === 0 && entry.lastUsed === 0) return undefined;
-	return entry;
-}
-
-/** In-memory usage table with an explicit, debounced flush. */
-export class UsageStore {
-	private docs = new Map<string, UsageEntry>();
-	private changed = false;
-	private saving?: Promise<void>;
-	private lastSessionAt = 0;
-
-	constructor(root: string) {
-		this.root = root;
-	}
-
-	private readonly root: string;
-
-	/** Load `<root>/.index/usage.json`; a missing or corrupt file starts empty. */
-	static async load(root: string): Promise<UsageStore> {
-		const store = new UsageStore(root);
-		const raw = await readFileOrUndefined(join(root, INDEX_DIR, USAGE_FILE));
-		if (!raw) return store;
-		try {
-			const parsed = JSON.parse(raw) as UsageFile;
-			if (!parsed || typeof parsed !== "object" || !parsed.docs || typeof parsed.docs !== "object") return store;
-			if (typeof parsed.lastSessionAt === "number" && Number.isFinite(parsed.lastSessionAt)) store.lastSessionAt = parsed.lastSessionAt;
-			for (const [id, value] of Object.entries(parsed.docs)) {
-				const entry = coerceEntry(value);
-				if (entry) store.docs.set(id, entry);
-			}
-		} catch {
-			// Derived data: a corrupt file is simply ignored.
-		}
-		return store;
-	}
-
-	get(id: string): UsageEntry | undefined {
-		return this.docs.get(id);
-	}
-
-	/** Count one retrieval (`hit`) or one fact write (`write`). */
-	record(id: string, kind: "hit" | "write", at = Date.now()): void {
-		if (!id) return;
-		let entry = this.docs.get(id);
-		if (!entry) {
-			entry = emptyEntry();
-			this.docs.set(id, entry);
-		}
-		if (kind === "hit") entry.hits += 1;
-		else entry.writes += 1;
-		if (at > entry.lastUsed) entry.lastUsed = at;
-		this.changed = true;
-	}
-
-	/** Note that a note was touched without counting a read or a write. */
-	markUsed(id: string, at: number): void {
-		const entry = this.docs.get(id);
-		if (entry) {
-			if (at > entry.lastUsed) {
-				entry.lastUsed = at;
-				this.changed = true;
-			}
-			return;
-		}
-		this.docs.set(id, { hits: 0, writes: 0, lastUsed: at });
-		this.changed = true;
-	}
-
-	entries(): Array<[string, UsageEntry]> {
-		return [...this.docs.entries()];
-	}
-
-	get size(): number {
-		return this.docs.size;
-	}
-
-	get dirty(): boolean {
-		return this.changed;
-	}
-
-	/** Drop entries whose note no longer exists, then cap the table size. */
-	prune(validIds: Set<string>): number {
-		let removed = 0;
-		for (const id of [...this.docs.keys()]) {
-			if (!validIds.has(id)) {
-				this.docs.delete(id);
-				removed += 1;
-			}
-		}
-		if (this.docs.size > MAX_USAGE_ENTRIES) {
-			const byAge = [...this.docs.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed);
-			for (const [id] of byAge.slice(0, this.docs.size - MAX_USAGE_ENTRIES)) {
-				this.docs.delete(id);
-				removed += 1;
-			}
-		}
-		if (removed > 0) this.changed = true;
-		return removed;
-	}
-
-	/** Epoch ms of the previous session start (0 when unknown). */
-	sessionStartedAt(): number {
-		return this.lastSessionAt;
-	}
-
-	/** Record this session's start so the next one can summarise what changed. */
-	markSessionStart(at = Date.now()): void {
-		this.lastSessionAt = at;
-		this.changed = true;
-	}
-
-	async save(): Promise<void> {
-		if (this.saving) {
-			await this.saving;
-			return this.save();
-		}
-		if (!this.changed) return;
-		this.changed = false;
-		const payload: UsageFile = { version: USAGE_VERSION, docs: Object.fromEntries(this.docs), lastSessionAt: this.lastSessionAt };
-		const saving = atomicWriteFile(join(this.root, INDEX_DIR, USAGE_FILE), JSON.stringify(payload));
-		this.saving = saving;
-		try {
-			await saving;
-		} catch (error) {
-			this.changed = true;
-			throw error;
-		} finally {
-			if (this.saving === saving) this.saving = undefined;
-		}
-	}
-
-	/** Notes with no recorded use in `staleMs`, oldest first. */
-	stale(staleMs: number, now = Date.now(), minWrites = 1): Array<{ id: string; entry: UsageEntry; idleMs: number }> {
-		const out: Array<{ id: string; entry: UsageEntry; idleMs: number }> = [];
-		for (const [id, entry] of this.docs) {
-			if (entry.writes < minWrites && entry.hits === 0) continue;
-			const idleMs = now - (entry.lastUsed || 0);
-			if (idleMs >= staleMs) out.push({ id, entry, idleMs });
-		}
-		return out.sort((a, b) => b.idleMs - a.idleMs);
-	}
-
-	/** Notes written often enough to be worth promoting into MEMORY.md. */
-	promotionCandidates(minWrites: number): Array<{ id: string; entry: UsageEntry }> {
-		const out: Array<{ id: string; entry: UsageEntry }> = [];
-		for (const [id, entry] of this.docs) if (entry.writes >= minWrites) out.push({ id, entry });
-		return out.sort((a, b) => b.entry.writes - a.entry.writes);
-	}
-}
-
-/** Human-readable idle duration, e.g. "3 months" or "12 days". */
-export function describeAge(ms: number): string {
-	const days = Math.floor(ms / 86_400_000);
-	if (days < 1) return "today";
-	if (days < 45) return `${days} day${days === 1 ? "" : "s"}`;
-	const months = Math.round(days / 30);
-	if (months < 18) return `${months} months`;
-	const years = Math.max(1, Math.round(days / 365));
-	return `${years} year${years === 1 ? "" : "s"}`;
-}

package/src/util.ts

@@ -1,141 +0,0 @@
-/**
- * Small dependency-free helpers shared across memoria.
- */
-
-import { createHash, randomBytes } from "node:crypto";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-/** Generate a stable-ish memory id: `mem_<epochms>_<6 hex>`. */
-export function newMemoryId(now = Date.now()): string {
-	return `mem_${now}_${randomBytes(3).toString("hex")}`;
-}
-
-/** Short sha1 fingerprint of a string. */
-export function shortHash(input: string): string {
-	return createHash("sha1").update(input).digest("hex").slice(0, 12);
-}
-
-/** Truncate to `max` characters without splitting a surrogate pair. */
-export function truncateChars(input: string, max: number): string {
-	if (max <= 0) return "";
-	if (input.length <= max) return input;
-	let end = max;
-	const code = input.charCodeAt(end - 1);
-	if (code >= 0xd800 && code <= 0xdbff) end -= 1;
-	return input.slice(0, end);
-}
-
-/** Collapse runs of whitespace, trim, and optionally truncate. */
-export function oneLine(input: string, max = Number.POSITIVE_INFINITY): string {
-	const flat = input.replace(/\s+/g, " ").trim();
-	return flat.length > max ? `${truncateChars(flat, Math.max(1, max - 1))}…` : flat;
-}
-
-/**
- * Keyed async mutex. Serializes read-modify-write sequences on the same key
- * (typically a store root) so concurrent tool calls cannot lose writes.
- */
-export class KeyedMutex {
-	private tails = new Map<string, Promise<void>>();
-
-	async run<T>(key: string, fn: () => Promise<T> | T): Promise<T> {
-		const previous = this.tails.get(key) ?? Promise.resolve();
-		let release!: () => void;
-		const current = new Promise<void>((resolve) => {
-			release = resolve;
-		});
-		const tail = previous.catch(() => {}).then(() => current);
-		this.tails.set(key, tail);
-		await previous.catch(() => {});
-		try {
-			return await fn();
-		} finally {
-			release();
-			if (this.tails.get(key) === tail) this.tails.delete(key);
-		}
-	}
-}
-
-/** Debounce a function; the trailing call wins. */
-export function debounce<A extends unknown[]>(fn: (...args: A) => void, waitMs: number): ((...args: A) => void) & { flush: () => void; cancel: () => void } {
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	let lastArgs: A | undefined;
-	const flush = () => {
-		if (timer === undefined) return;
-		clearTimeout(timer);
-		timer = undefined;
-		const args = lastArgs;
-		lastArgs = undefined;
-		if (args) fn(...args);
-	};
-	const cancel = () => {
-		if (timer !== undefined) clearTimeout(timer);
-		timer = undefined;
-		lastArgs = undefined;
-	};
-	const wrapped = (...args: A) => {
-		lastArgs = args;
-		if (timer !== undefined) clearTimeout(timer);
-		timer = setTimeout(() => {
-			timer = undefined;
-			const callArgs = lastArgs;
-			lastArgs = undefined;
-			if (callArgs) fn(...callArgs);
-		}, waitMs);
-		timer.unref?.();
-	};
-	return Object.assign(wrapped, { flush, cancel });
-}
-
-/** Write a file atomically (temp file + rename), creating parent dirs. */
-export async function atomicWriteFile(path: string, data: string | Uint8Array): Promise<void> {
-	await mkdir(dirname(path), { recursive: true });
-	const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
-	try {
-		await (typeof data === "string" ? writeFile(tmp, data, "utf8") : writeFile(tmp, data));
-		await rename(tmp, path);
-	} catch (error) {
-		await rm(tmp, { force: true }).catch(() => {});
-		throw error;
-	}
-}
-
-/** Read a file as utf8, returning undefined when it does not exist. */
-export async function readFileOrUndefined(path: string): Promise<string | undefined> {
-	try {
-		return await readFile(path, "utf8");
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-		throw error;
-	}
-}
-
-/** Read a file as bytes, returning undefined when it does not exist. */
-export async function readFileBufferOrUndefined(path: string): Promise<Buffer | undefined> {
-	try {
-		return await readFile(path);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-		throw error;
-	}
-}
-
-/** Normalize a path for comparisons: forward slashes, no trailing slash. */
-export function normalizePath(input: string): string {
-	const slashed = input.replace(/\\/g, "/");
-	return slashed.length > 1 ? slashed.replace(/\/+$/, "") : slashed;
-}
-
-/** Move to trash (soft delete) instead of hard deleting. */
-export async function moveToTrash(path: string, trashDir: string): Promise<string> {
-	await mkdir(trashDir, { recursive: true });
-	const base = path.split("/").pop() ?? "memory.md";
-	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-	// Different categories can contain the same basename and be removed within
-	// one millisecond. A random suffix prevents rename() from replacing the
-	// earlier trashed file on POSIX filesystems.
-	const target = join(trashDir, `${stamp}_${randomBytes(8).toString("hex")}__${base}`);
-	await rename(path, target);
-	return target;
-}