@drewpayment/mink 0.1.0

package/src/core/cron-parser.ts

@@ -0,0 +1,94 @@
+import type { CronSchedule } from "../types/scheduler";
+
+// ── Field Parsing ───────────────────────────────────────────────────────────
+
+function parseField(field: string, min: number, max: number): number[] {
+  const values = new Set<number>();
+
+  for (const part of field.split(",")) {
+    if (part === "*") {
+      for (let i = min; i <= max; i++) values.add(i);
+    } else if (part.includes("/")) {
+      const [range, stepStr] = part.split("/");
+      const step = parseInt(stepStr, 10);
+      if (isNaN(step) || step <= 0) {
+        throw new Error(`Invalid step value: ${part}`);
+      }
+      const start = range === "*" ? min : parseInt(range, 10);
+      if (isNaN(start) || start < min || start > max) {
+        throw new Error(`Invalid range start: ${part}`);
+      }
+      for (let i = start; i <= max; i += step) values.add(i);
+    } else if (part.includes("-")) {
+      const [lo, hi] = part.split("-").map(Number);
+      if (isNaN(lo) || isNaN(hi) || lo < min || hi > max || lo > hi) {
+        throw new Error(`Invalid range: ${part}`);
+      }
+      for (let i = lo; i <= hi; i++) values.add(i);
+    } else {
+      const n = parseInt(part, 10);
+      if (isNaN(n) || n < min || n > max) {
+        throw new Error(`Invalid value: ${part} (must be ${min}-${max})`);
+      }
+      values.add(n);
+    }
+  }
+
+  return [...values].sort((a, b) => a - b);
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+export function parseCronExpression(expr: string): CronSchedule {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(
+      `Invalid cron expression: expected 5 fields, got ${fields.length}`
+    );
+  }
+
+  return {
+    minute: parseField(fields[0], 0, 59),
+    hour: parseField(fields[1], 0, 23),
+    dayOfMonth: parseField(fields[2], 1, 31),
+    month: parseField(fields[3], 1, 12),
+    dayOfWeek: parseField(fields[4], 0, 6),
+  };
+}
+
+function matches(schedule: CronSchedule, date: Date): boolean {
+  return (
+    schedule.minute.includes(date.getUTCMinutes()) &&
+    schedule.hour.includes(date.getUTCHours()) &&
+    schedule.dayOfMonth.includes(date.getUTCDate()) &&
+    schedule.month.includes(date.getUTCMonth() + 1) &&
+    schedule.dayOfWeek.includes(date.getUTCDay())
+  );
+}
+
+export function nextRunAfter(schedule: CronSchedule, after: Date): Date {
+  // Start from the next whole minute
+  const candidate = new Date(after.getTime());
+  candidate.setUTCSeconds(0, 0);
+  candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+
+  const limit = after.getTime() + 366 * 24 * 60 * 60 * 1000;
+
+  while (candidate.getTime() <= limit) {
+    if (matches(schedule, candidate)) {
+      return candidate;
+    }
+    candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+  }
+
+  throw new Error("No matching time found within 366 days");
+}
+
+export function isInCurrentPeriod(
+  schedule: CronSchedule,
+  lastRun: Date,
+  now: Date
+): boolean {
+  const next = nextRunAfter(schedule, lastRun);
+  return now.getTime() < next.getTime();
+}

package/src/core/daemon.ts

@@ -0,0 +1,152 @@
+import { readFileSync, writeFileSync, unlinkSync, existsSync, openSync } from "fs";
+import { mkdirSync } from "fs";
+import { dirname, resolve } from "path";
+import { schedulerPidPath, schedulerLogPath } from "./paths";
+import type { PidFileData } from "../types/scheduler";
+
+// ── PID File Operations ─────────────────────────────────────────────────────
+
+export function readPidFile(): PidFileData | null {
+  try {
+    const raw = readFileSync(schedulerPidPath(), "utf-8");
+    const data = JSON.parse(raw);
+    if (
+      data &&
+      typeof data.pid === "number" &&
+      typeof data.startedAt === "string" &&
+      typeof data.projectCwd === "string"
+    ) {
+      return data as PidFileData;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function writePidFile(data: PidFileData): void {
+  const pidPath = schedulerPidPath();
+  mkdirSync(dirname(pidPath), { recursive: true });
+  writeFileSync(pidPath, JSON.stringify(data, null, 2));
+}
+
+export function removePidFile(): void {
+  try {
+    unlinkSync(schedulerPidPath());
+  } catch {
+    // Already removed
+  }
+}
+
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Daemon Lifecycle ────────────────────────────────────────────────────────
+
+export function startDaemon(cwd: string): void {
+  const existing = readPidFile();
+  if (existing && isProcessAlive(existing.pid)) {
+    console.log(
+      `[mink] scheduler is already running (PID: ${existing.pid})`
+    );
+    return;
+  }
+
+  // Clean up stale PID file
+  if (existing) {
+    removePidFile();
+  }
+
+  // Resolve the CLI entry point
+  const cliPath = resolve(import.meta.dir, "../cli.ts");
+
+  // Ensure log directory exists
+  const logPath = schedulerLogPath();
+  mkdirSync(dirname(logPath), { recursive: true });
+  const logFd = openSync(logPath, "a");
+
+  const proc = Bun.spawn(["bun", "run", cliPath, "cron", "__daemon"], {
+    cwd,
+    stdout: logFd,
+    stderr: logFd,
+    stdin: "ignore",
+    env: process.env,
+  });
+
+  // Unref so parent can exit
+  proc.unref();
+
+  writePidFile({
+    pid: proc.pid,
+    startedAt: new Date().toISOString(),
+    projectCwd: cwd,
+  });
+
+  console.log(`[mink] scheduler started (PID: ${proc.pid})`);
+  console.log(`[mink] log: ${logPath}`);
+}
+
+export async function stopDaemon(): Promise<void> {
+  const pidData = readPidFile();
+  if (!pidData) {
+    console.log("[mink] scheduler is not running (no PID file)");
+    return;
+  }
+
+  if (!isProcessAlive(pidData.pid)) {
+    console.log("[mink] scheduler is not running (stale PID file)");
+    removePidFile();
+    return;
+  }
+
+  // Send SIGTERM
+  process.kill(pidData.pid, "SIGTERM");
+  console.log(`[mink] sent SIGTERM to PID ${pidData.pid}`);
+
+  // Poll for up to 5 seconds
+  for (let i = 0; i < 50; i++) {
+    await new Promise((r) => setTimeout(r, 100));
+    if (!isProcessAlive(pidData.pid)) {
+      removePidFile();
+      console.log("[mink] scheduler stopped");
+      return;
+    }
+  }
+
+  // Force kill
+  try {
+    process.kill(pidData.pid, "SIGKILL");
+  } catch {
+    // Process may have just exited
+  }
+  removePidFile();
+  console.log("[mink] scheduler force-stopped (SIGKILL)");
+}
+
+export function getDaemonStatus(cwd: string): {
+  running: boolean;
+  pid?: number;
+  startedAt?: string;
+  projectCwd?: string;
+} {
+  const pidData = readPidFile();
+  if (!pidData) {
+    return { running: false };
+  }
+  if (!isProcessAlive(pidData.pid)) {
+    removePidFile();
+    return { running: false };
+  }
+  return {
+    running: true,
+    pid: pidData.pid,
+    startedAt: pidData.startedAt,
+    projectCwd: pidData.projectCwd,
+  };
+}

package/src/core/dashboard-api.ts

@@ -0,0 +1,280 @@
+import { existsSync, readFileSync } from "fs";
+import {
+  projectDir,
+  fileIndexPath,
+  tokenLedgerPath,
+  bugMemoryPath,
+  actionLogPath,
+  learningMemoryPath,
+  projectMetaPath,
+  sessionPath,
+  configPath,
+  schedulerManifestPath,
+  designReportPath,
+} from "./paths";
+import { safeReadJson } from "./fs-utils";
+import { isFileIndex } from "./index-store";
+import { loadLedger } from "./token-ledger";
+import { parseLearningMemory } from "./learning-memory";
+import { loadBugMemory } from "./bug-memory";
+import { safeReadLog, parseLogSessions } from "./action-log";
+import { getDaemonStatus } from "./daemon";
+import { loadManifest, removeFromDeadLetter, saveManifest } from "./scheduler";
+import { getBuiltInTasks, executeTask } from "./task-registry";
+import type {
+  OverviewPayload,
+  TokenLedgerPayload,
+  FileIndexPayload,
+  SchedulerPayload,
+  BugLogPayload,
+  ActionLogPayload,
+  ActionResult,
+  FileStatus,
+  DesignPayload,
+} from "../types/dashboard";
+import { isDesignEvalReport } from "../types/design-eval";
+import type { DesignEvalReport } from "../types/design-eval";
+import type { FileIndex, FileIndexEntry } from "../types/file-index";
+import type { LearningMemory } from "../types/learning-memory";
+
+// ── File Status Checks ─────────────────────────────────────────────────────
+
+function checkJsonFile(
+  name: string,
+  filePath: string,
+  validator?: (v: unknown) => boolean
+): FileStatus {
+  if (!existsSync(filePath)) return { name, status: "missing" };
+  const data = safeReadJson(filePath);
+  if (data === null) return { name, status: "corrupt" };
+  if (validator && !validator(data)) return { name, status: "corrupt" };
+  return { name, status: "ok" };
+}
+
+function checkTextFile(name: string, filePath: string): FileStatus {
+  if (!existsSync(filePath)) return { name, status: "missing" };
+  try {
+    readFileSync(filePath, "utf-8");
+    return { name, status: "ok" };
+  } catch {
+    return { name, status: "corrupt" };
+  }
+}
+
+// ── Panel Loaders ──────────────────────────────────────────────────────────
+
+export function loadOverview(cwd: string): OverviewPayload {
+  // Project metadata
+  let project: OverviewPayload["project"] = null;
+  const meta = safeReadJson(projectMetaPath(cwd)) as {
+    name?: string;
+    description?: string;
+  } | null;
+  if (meta && typeof meta === "object") {
+    project = {
+      name: meta.name ?? "Unknown",
+      description: meta.description ?? "",
+      cwd,
+    };
+  }
+
+  // Daemon status
+  const daemonStatus = getDaemonStatus(cwd);
+  const daemon: OverviewPayload["daemon"] = {
+    running: daemonStatus.running,
+    pid: daemonStatus.pid,
+    startedAt: daemonStatus.startedAt,
+    uptimeMs: daemonStatus.startedAt
+      ? Date.now() - new Date(daemonStatus.startedAt).getTime()
+      : undefined,
+  };
+
+  // Token ledger summary
+  const ledger = loadLedger(tokenLedgerPath(cwd));
+  const summary = {
+    totalSessions: ledger.lifetime.totalSessions,
+    totalTokens: ledger.lifetime.totalTokens,
+    totalReads: ledger.lifetime.totalReads,
+    totalWrites: ledger.lifetime.totalWrites,
+    estimatedSavings: ledger.lifetime.totalEstimatedSavings,
+  };
+
+  // State file health
+  const stateFiles: FileStatus[] = [
+    checkJsonFile("session.json", sessionPath(cwd)),
+    checkJsonFile("file-index.json", fileIndexPath(cwd), isFileIndex),
+    checkJsonFile("config.json", configPath(cwd)),
+    checkTextFile("learning-memory.md", learningMemoryPath(cwd)),
+    checkJsonFile("token-ledger.json", tokenLedgerPath(cwd)),
+    checkJsonFile("bug-memory.json", bugMemoryPath(cwd)),
+    checkTextFile("action-log.md", actionLogPath(cwd)),
+    checkJsonFile("scheduler-manifest.json", schedulerManifestPath(cwd)),
+  ];
+
+  return { project, daemon, summary, stateFiles };
+}
+
+export function loadTokenLedgerPanel(cwd: string): TokenLedgerPayload {
+  const ledger = loadLedger(tokenLedgerPath(cwd));
+  return {
+    lifetime: ledger.lifetime,
+    sessions: ledger.sessions,
+    wasteFlags: ledger.wasteFlags ?? [],
+  };
+}
+
+export function loadFileIndexPanel(cwd: string): FileIndexPayload {
+  const raw = safeReadJson(fileIndexPath(cwd));
+  if (raw && isFileIndex(raw)) {
+    const index = raw as FileIndex;
+    const entries: FileIndexEntry[] = Object.values(index.entries);
+    return { header: index.header, entries };
+  }
+  return {
+    header: {
+      lastScanTimestamp: "",
+      totalFiles: 0,
+      lifetimeHits: 0,
+      lifetimeMisses: 0,
+    },
+    entries: [],
+  };
+}
+
+export function loadSchedulerPanel(cwd: string): SchedulerPayload {
+  const manifest = loadManifest(cwd);
+  const definitions = getBuiltInTasks();
+
+  const tasks = definitions.map((def) => {
+    const state = manifest?.tasks.find((t) => t.taskId === def.id) ?? null;
+    return { definition: def, state };
+  });
+
+  return {
+    tasks,
+    deadLetterQueue: manifest?.deadLetterQueue ?? [],
+    lastHeartbeat: manifest?.lastHeartbeat ?? null,
+  };
+}
+
+export function loadLearningMemoryPanel(cwd: string): LearningMemory {
+  const memPath = learningMemoryPath(cwd);
+  if (!existsSync(memPath)) {
+    return {
+      projectName: "unknown",
+      sections: {
+        "User Preferences": [],
+        "Key Learnings": [],
+        "Do-Not-Repeat": [],
+        "Decision Log": [],
+      },
+    };
+  }
+  try {
+    const content = readFileSync(memPath, "utf-8");
+    return parseLearningMemory(content);
+  } catch {
+    return {
+      projectName: "unknown",
+      sections: {
+        "User Preferences": [],
+        "Key Learnings": [],
+        "Do-Not-Repeat": [],
+        "Decision Log": [],
+      },
+    };
+  }
+}
+
+export function loadActionLogPanel(cwd: string): ActionLogPayload {
+  const content = safeReadLog(actionLogPath(cwd));
+  const sessions = parseLogSessions(content);
+  return { sessions };
+}
+
+export function loadBugLogPanel(cwd: string): BugLogPayload {
+  const memory = loadBugMemory(bugMemoryPath(cwd));
+  return { entries: memory.entries, nextId: memory.nextId };
+}
+
+export function loadDesignPanel(cwd: string): DesignPayload {
+  const raw = safeReadJson(designReportPath(cwd));
+  if (!raw || !isDesignEvalReport(raw)) {
+    return { images: [] };
+  }
+
+  const report = raw as DesignEvalReport;
+  return {
+    images: report.captures.map((c) => ({
+      url: `/api/design-images/${c.fileName}`,
+      route: c.route,
+      viewport: c.viewport,
+      section: c.section,
+      timestamp: c.timestamp,
+    })),
+  };
+}
+
+// ── Action Triggers ────────────────────────────────────────────────────────
+
+export async function triggerTask(
+  cwd: string,
+  taskId: string
+): Promise<ActionResult> {
+  try {
+    await executeTask(taskId, cwd);
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function triggerDeadLetterRetry(
+  cwd: string,
+  taskId: string
+): Promise<ActionResult> {
+  try {
+    const manifest = loadManifest(cwd);
+    if (!manifest) {
+      return { success: false, error: "No scheduler manifest found" };
+    }
+
+    const entry = removeFromDeadLetter(manifest, taskId);
+    if (!entry) {
+      return { success: false, error: `Task ${taskId} not in dead letter queue` };
+    }
+
+    // Reset the task record
+    const record = manifest.tasks.find((t) => t.taskId === taskId);
+    if (record) {
+      record.status = "idle";
+      record.consecutiveFailures = 0;
+      record.currentAttempt = 0;
+    }
+
+    saveManifest(cwd, manifest);
+    await executeTask(taskId, cwd);
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function triggerRescan(cwd: string): Promise<ActionResult> {
+  try {
+    const { scan } = await import("../commands/scan");
+    scan(cwd, { check: false });
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}