agent-optic 0.2.0

package/src/utils/dates.ts

@@ -0,0 +1,40 @@
+/** Convert a timestamp (ms) to YYYY-MM-DD in local time. */
+export function toLocalDate(timestamp: number): string {
+	const d = new Date(timestamp);
+	const year = d.getFullYear();
+	const month = String(d.getMonth() + 1).padStart(2, "0");
+	const day = String(d.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}
+
+/** Get today's date as YYYY-MM-DD. */
+export function today(): string {
+	return toLocalDate(Date.now());
+}
+
+/** Format a timestamp to HH:MM (24h). */
+export function formatTime(timestamp: number): string {
+	const d = new Date(timestamp);
+	const h = String(d.getHours()).padStart(2, "0");
+	const m = String(d.getMinutes()).padStart(2, "0");
+	return `${h}:${m}`;
+}
+
+/** Resolve a DateFilter to concrete from/to strings. */
+export function resolveDateRange(filter?: {
+	date?: string;
+	from?: string;
+	to?: string;
+}): { from: string; to: string } {
+	if (filter?.date) {
+		return { from: filter.date, to: filter.date };
+	}
+	if (filter?.from && filter?.to) {
+		return { from: filter.from, to: filter.to };
+	}
+	if (filter?.from) {
+		return { from: filter.from, to: today() };
+	}
+	const t = today();
+	return { from: t, to: t };
+}

package/src/utils/jsonl.ts

@@ -0,0 +1,83 @@
+/** Parse all lines from a JSONL string, skipping malformed lines. */
+export function parseJsonl<T>(text: string): T[] {
+	const results: T[] = [];
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			results.push(JSON.parse(line) as T);
+		} catch {
+			// skip malformed
+		}
+	}
+	return results;
+}
+
+/** Stream-parse JSONL from a file, yielding each parsed line. */
+export async function* streamJsonl<T>(filePath: string): AsyncGenerator<T> {
+	const file = Bun.file(filePath);
+	if (!(await file.exists())) return;
+
+	const text = await file.text();
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			yield JSON.parse(line) as T;
+		} catch {
+			// skip malformed
+		}
+	}
+}
+
+/** Peek a JSONL file — read only first N and last N bytes for metadata extraction. */
+export async function peekJsonl(
+	filePath: string,
+	bytes: number = 4096,
+): Promise<{ first: unknown[]; last: unknown[]; totalBytes: number }> {
+	const file = Bun.file(filePath);
+	if (!(await file.exists())) return { first: [], last: [], totalBytes: 0 };
+
+	const size = file.size;
+
+	if (size <= bytes * 2) {
+		// Small file: just read the whole thing
+		const text = await file.text();
+		const lines = parseJsonl<unknown>(text);
+		return { first: lines, last: [], totalBytes: size };
+	}
+
+	// Read first chunk
+	const firstChunk = await file.slice(0, bytes).text();
+	const firstLines = firstChunk.split("\n").filter((l) => l.trim());
+	const first: unknown[] = [];
+	for (const line of firstLines.slice(0, -1)) {
+		// Skip last line of chunk (may be truncated)
+		try {
+			first.push(JSON.parse(line));
+		} catch {
+			// skip
+		}
+	}
+
+	// Read last chunk
+	const lastChunk = await file.slice(Math.max(0, size - bytes), size).text();
+	const lastLines = lastChunk.split("\n").filter((l) => l.trim());
+	const last: unknown[] = [];
+	for (const line of lastLines.slice(1)) {
+		// Skip first line of chunk (may be truncated)
+		try {
+			last.push(JSON.parse(line));
+		} catch {
+			// skip
+		}
+	}
+
+	return { first, last, totalBytes: size };
+}
+
+/** Read and parse an entire JSONL file. */
+export async function readJsonl<T>(filePath: string): Promise<T[]> {
+	const file = Bun.file(filePath);
+	if (!(await file.exists())) return [];
+	const text = await file.text();
+	return parseJsonl<T>(text);
+}

package/src/utils/paths.ts

@@ -0,0 +1,57 @@
+import { join } from "node:path";
+import type { Provider } from "../types/provider.js";
+import { DEFAULT_PROVIDER, defaultProviderDir } from "./providers.js";
+
+/** Encode a project path for filesystem storage (/ → -). */
+export function encodeProjectPath(projectPath: string): string {
+	return projectPath.replace(/\//g, "-");
+}
+
+/** Decode an encoded project path back to original (- → /). Best-effort: ambiguous. */
+export function decodeProjectPath(encoded: string): string {
+	return encoded.replace(/-/g, "/");
+}
+
+/** Extract a short project name from a full path. */
+export function projectName(projectPath: string): string {
+	return projectPath.split("/").pop() || projectPath;
+}
+
+export interface ProviderPaths {
+	base: string;
+	historyFile: string;
+	projectsDir: string;
+	sessionsDir: string;
+	globalStateFile: string;
+	tasksDir: string;
+	plansDir: string;
+	todosDir: string;
+	skillsDir: string;
+	statsCache: string;
+}
+
+/** Build all standard paths relative to a provider directory. */
+export function providerPaths(config?: {
+	provider?: Provider;
+	providerDir?: string;
+}): ProviderPaths {
+	const provider = config?.provider ?? DEFAULT_PROVIDER;
+	const base = config?.providerDir ?? defaultProviderDir(provider);
+	return {
+		base,
+		historyFile: join(base, "history.jsonl"),
+		projectsDir: join(base, "projects"),
+		sessionsDir: join(base, "sessions"),
+		globalStateFile: join(base, ".codex-global-state.json"),
+		tasksDir: join(base, "tasks"),
+		plansDir: join(base, "plans"),
+		todosDir: join(base, "todos"),
+		skillsDir: join(base, "skills"),
+		statsCache: join(base, "stats-cache.json"),
+	};
+}
+
+/** Backward-compatible alias for Claude-specific default paths. */
+export function claudePaths(claudeDir?: string): ProviderPaths {
+	return providerPaths({ provider: "claude", providerDir: claudeDir });
+}

package/src/utils/providers.ts

@@ -0,0 +1,30 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Provider } from "../types/provider.js";
+
+const PROVIDER_HOME_DIR: Record<Provider, string> = {
+	claude: ".claude",
+	codex: ".codex",
+	openai: ".codex",
+	cursor: ".cursor",
+	windsurf: ".windsurf",
+};
+
+export const DEFAULT_PROVIDER: Provider = "claude";
+
+export function defaultProviderDir(provider: Provider): string {
+	return join(homedir(), PROVIDER_HOME_DIR[provider]);
+}
+
+export function providerHomeDirName(provider: Provider): string {
+	return PROVIDER_HOME_DIR[provider];
+}
+
+export function isProvider(value: string): value is Provider {
+	return value in PROVIDER_HOME_DIR;
+}
+
+export function canonicalProvider(provider: Provider): Exclude<Provider, "openai"> {
+	if (provider === "openai") return "codex";
+	return provider;
+}