@drewpayment/mink 0.1.0

package/src/commands/cron.ts

@@ -0,0 +1,295 @@
+import { startDaemon, stopDaemon, getDaemonStatus, removePidFile } from "../core/daemon";
+import { createScheduler, loadManifest, removeFromDeadLetter, saveManifest, createInitialManifest, recoverManifest } from "../core/scheduler";
+import { getBuiltInTasks, getTaskById, executeTask } from "../core/task-registry";
+import { schedulerManifestPath } from "../core/paths";
+
+// ── Subcommand: start ───────────────────────────────────────────────────────
+
+function cronStart(cwd: string): void {
+  startDaemon(cwd);
+}
+
+// ── Subcommand: stop ────────────────────────────────────────────────────────
+
+async function cronStop(): Promise<void> {
+  await stopDaemon();
+}
+
+// ── Subcommand: status ──────────────────────────────────────────────────────
+
+function cronStatus(cwd: string): void {
+  const status = getDaemonStatus(cwd);
+
+  if (!status.running) {
+    console.log("[mink] scheduler is not running");
+  } else {
+    const uptimeMs = Date.now() - new Date(status.startedAt!).getTime();
+    const uptimeMin = Math.floor(uptimeMs / 60_000);
+    const uptimeHrs = Math.floor(uptimeMin / 60);
+    const uptimeStr =
+      uptimeHrs > 0
+        ? `${uptimeHrs}h ${uptimeMin % 60}m`
+        : `${uptimeMin}m`;
+
+    console.log(`[mink] scheduler running (PID: ${status.pid})`);
+    console.log(`  Started: ${status.startedAt}`);
+    console.log(`  Uptime:  ${uptimeStr}`);
+    console.log(`  Project: ${status.projectCwd}`);
+  }
+
+  const manifest = loadManifest(cwd);
+  if (manifest) {
+    console.log(`  Last heartbeat: ${manifest.lastHeartbeat}`);
+    console.log(`  Dead letter queue: ${manifest.deadLetterQueue.length} task(s)`);
+    console.log();
+    cronList(cwd);
+  }
+}
+
+// ── Subcommand: list ────────────────────────────────────────────────────────
+
+function cronList(cwd: string): void {
+  const tasks = getBuiltInTasks();
+  const manifest = loadManifest(cwd);
+
+  console.log("Tasks:");
+  console.log(
+    "  " +
+      "ID".padEnd(30) +
+      "Schedule".padEnd(18) +
+      "Status".padEnd(16) +
+      "Last Run"
+  );
+  console.log("  " + "-".repeat(80));
+
+  for (const task of tasks) {
+    const record = manifest?.tasks.find((r) => r.taskId === task.id);
+    const status = record?.status ?? "idle";
+    const lastRun = record?.lastRunAt
+      ? new Date(record.lastRunAt).toISOString().replace("T", " ").slice(0, 19)
+      : "never";
+
+    console.log(
+      "  " +
+        task.id.padEnd(30) +
+        task.schedule.padEnd(18) +
+        status.padEnd(16) +
+        lastRun
+    );
+  }
+}
+
+// ── Subcommand: run ─────────────────────────────────────────────────────────
+
+async function cronRun(cwd: string, taskId: string | undefined): Promise<void> {
+  if (!taskId) {
+    console.error("Usage: mink cron run <task-id>");
+    console.error(
+      "Available tasks: " + getBuiltInTasks().map((t) => t.id).join(", ")
+    );
+    process.exit(1);
+  }
+
+  const task = getTaskById(taskId);
+  if (!task) {
+    console.error(`[mink] unknown task: ${taskId}`);
+    console.error(
+      "Available tasks: " + getBuiltInTasks().map((t) => t.id).join(", ")
+    );
+    process.exit(1);
+  }
+
+  console.log(`[mink] running task: ${task.name}`);
+
+  // Execute directly, with retry logic
+  let lastError: Error | null = null;
+  for (let attempt = 0; attempt < task.retryPolicy.maxAttempts; attempt++) {
+    try {
+      await executeTask(taskId, cwd);
+      console.log(`[mink] task ${taskId} completed successfully`);
+      return;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      console.error(
+        `[mink] task ${taskId} failed (attempt ${attempt + 1}/${task.retryPolicy.maxAttempts}): ${lastError.message}`
+      );
+
+      if (attempt + 1 < task.retryPolicy.maxAttempts) {
+        const delay = task.retryPolicy.baseDelayMs * Math.pow(2, attempt);
+        console.log(`[mink] retrying in ${Math.round(delay / 1000)}s...`);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+
+  // All retries exhausted — dead letter
+  console.error(
+    `[mink] task ${taskId} failed after ${task.retryPolicy.maxAttempts} attempts`
+  );
+
+  // Update manifest if it exists
+  let manifest = loadManifest(cwd);
+  if (manifest) {
+    const record = manifest.tasks.find((r) => r.taskId === taskId);
+    if (record) {
+      record.status = "dead-lettered";
+    }
+    manifest.deadLetterQueue.push({
+      taskId,
+      deadLetteredAt: new Date().toISOString(),
+      failureTimestamps: [new Date().toISOString()],
+      errorMessages: [lastError?.message ?? "Unknown error"],
+      attemptCount: task.retryPolicy.maxAttempts,
+    });
+    saveManifest(cwd, manifest);
+  }
+
+  process.exit(1);
+}
+
+// ── Subcommand: dead-letter ─────────────────────────────────────────────────
+
+async function cronDeadLetter(
+  cwd: string,
+  args: string[]
+): Promise<void> {
+  const action = args[0];
+
+  if (action === "list") {
+    const manifest = loadManifest(cwd);
+    if (!manifest || manifest.deadLetterQueue.length === 0) {
+      console.log("[mink] dead letter queue is empty");
+      return;
+    }
+
+    console.log("Dead-lettered tasks:");
+    for (const entry of manifest.deadLetterQueue) {
+      console.log(`  ${entry.taskId}`);
+      console.log(`    Dead-lettered: ${entry.deadLetteredAt}`);
+      console.log(`    Attempts: ${entry.attemptCount}`);
+      console.log(
+        `    Last error: ${entry.errorMessages[entry.errorMessages.length - 1] ?? "unknown"}`
+      );
+    }
+    return;
+  }
+
+  if (action === "retry") {
+    const taskId = args[1];
+    if (!taskId) {
+      console.error("Usage: mink cron dead-letter retry <task-id>");
+      process.exit(1);
+    }
+
+    const manifest = loadManifest(cwd);
+    if (!manifest) {
+      console.error("[mink] no scheduler manifest found");
+      process.exit(1);
+    }
+
+    const entry = removeFromDeadLetter(manifest, taskId);
+    if (!entry) {
+      console.error(`[mink] task ${taskId} is not in the dead letter queue`);
+      process.exit(1);
+    }
+
+    // Reset the task record
+    const record = manifest.tasks.find((r) => r.taskId === taskId);
+    if (record) {
+      record.status = "idle";
+      record.currentAttempt = 0;
+    }
+    saveManifest(cwd, manifest);
+
+    console.log(`[mink] retrying dead-lettered task: ${taskId}`);
+    try {
+      await executeTask(taskId, cwd);
+      console.log(`[mink] task ${taskId} completed successfully`);
+      if (record) {
+        record.lastSuccessAt = new Date().toISOString();
+        record.lastRunAt = new Date().toISOString();
+        record.consecutiveFailures = 0;
+      }
+      saveManifest(cwd, manifest);
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      console.error(`[mink] task ${taskId} failed again: ${errorMsg}`);
+      // Re-add to dead letter
+      manifest.deadLetterQueue.push({
+        taskId,
+        deadLetteredAt: new Date().toISOString(),
+        failureTimestamps: [...entry.failureTimestamps, new Date().toISOString()],
+        errorMessages: [...entry.errorMessages, errorMsg],
+        attemptCount: entry.attemptCount + 1,
+      });
+      if (record) {
+        record.status = "dead-lettered";
+      }
+      saveManifest(cwd, manifest);
+      process.exit(1);
+    }
+    return;
+  }
+
+  console.error("Usage: mink cron dead-letter <list|retry> [task-id]");
+  process.exit(1);
+}
+
+// ── Subcommand: __daemon (internal) ─────────────────────────────────────────
+
+async function cronDaemon(cwd: string): Promise<void> {
+  console.log(`[mink] daemon starting for project: ${cwd}`);
+
+  const scheduler = createScheduler(cwd);
+
+  // Signal handlers for graceful shutdown
+  process.on("SIGTERM", () => {
+    console.log("[mink] received SIGTERM");
+    scheduler.stop();
+    removePidFile();
+    process.exit(0);
+  });
+
+  process.on("SIGINT", () => {
+    console.log("[mink] received SIGINT");
+    scheduler.stop();
+    removePidFile();
+    process.exit(0);
+  });
+
+  scheduler.start();
+
+  // Keep the process alive
+  await new Promise(() => {});
+}
+
+// ── Main Entry Point ────────────────────────────────────────────────────────
+
+export async function cron(cwd: string, args: string[]): Promise<void> {
+  const subcommand = args[0];
+
+  switch (subcommand) {
+    case "start":
+      return cronStart(cwd);
+    case "stop":
+      return await cronStop();
+    case "status":
+      return cronStatus(cwd);
+    case "list":
+      return cronList(cwd);
+    case "run":
+      return await cronRun(cwd, args[1]);
+    case "dead-letter":
+      return await cronDeadLetter(cwd, args.slice(1));
+    case "__daemon":
+      return await cronDaemon(cwd);
+    default:
+      console.error(
+        `[mink] unknown cron subcommand: ${subcommand ?? "(none)"}`
+      );
+      console.error(
+        "Usage: mink cron <start|stop|status|list|run|dead-letter>"
+      );
+      process.exit(1);
+  }
+}

package/src/commands/daemon.ts

@@ -0,0 +1,46 @@
+import { readFileSync, existsSync } from "fs";
+import { startDaemon, stopDaemon } from "../core/daemon";
+import { schedulerLogPath } from "../core/paths";
+
+export async function daemon(cwd: string, args: string[]): Promise<void> {
+  const subcommand = args[0];
+
+  switch (subcommand) {
+    case "start":
+      startDaemon(cwd);
+      break;
+
+    case "stop":
+      await stopDaemon();
+      break;
+
+    case "restart":
+      await stopDaemon();
+      startDaemon(cwd);
+      break;
+
+    case "logs": {
+      const logPath = schedulerLogPath();
+      if (!existsSync(logPath)) {
+        console.log("[mink] no log file found");
+        return;
+      }
+      try {
+        const content = readFileSync(logPath, "utf-8");
+        const lines = content.split("\n");
+        const tail = lines.slice(-50).join("\n");
+        console.log(tail);
+      } catch {
+        console.error("[mink] error reading log file");
+      }
+      break;
+    }
+
+    default:
+      console.error(
+        `[mink] unknown daemon subcommand: ${subcommand ?? "(none)"}`
+      );
+      console.error("Usage: mink daemon <start|stop|restart|logs>");
+      process.exit(1);
+  }
+}

package/src/commands/dashboard.ts

@@ -0,0 +1,21 @@
+import { existsSync } from "fs";
+import { projectDir } from "../core/paths";
+
+export async function dashboard(cwd: string, args: string[]): Promise<void> {
+  if (!existsSync(projectDir(cwd))) {
+    console.error("[mink] project not initialized. Run: mink init");
+    process.exit(1);
+  }
+
+  const portArg = args.find((a) => a.startsWith("--port="));
+  const port = portArg ? parseInt(portArg.split("=")[1], 10) : 4040;
+  const noOpen = args.includes("--no-open");
+
+  const { startDashboardServer } = await import("../core/dashboard-server");
+  const { url } = startDashboardServer(cwd, { port, open: !noOpen });
+
+  console.log(`[mink] dashboard running at ${url}`);
+  console.log("[mink] press Ctrl+C to stop");
+
+  await new Promise(() => {});
+}

package/src/commands/designqc.ts

@@ -0,0 +1,160 @@
+import { designCapturesDir, designReportPath } from "../core/paths";
+import { atomicWriteJson } from "../core/fs-utils";
+import { findRunningServer, detectDevCommand } from "../core/design-eval/server-detect";
+import { detectRoutes } from "../core/design-eval/route-detect";
+import { captureAllRoutes } from "../core/design-eval/capture";
+import {
+  DEFAULT_VIEWPORTS,
+  DEFAULT_QUALITY,
+  DEFAULT_MAX_SECTIONS,
+} from "../types/design-eval";
+import type { DesignQcOptions, Viewport } from "../types/design-eval";
+
+// ── Arg Parsing ───────────────────────────────────────────────────────────
+
+export function parseDesignQcArgs(args: string[]): DesignQcOptions {
+  const options: DesignQcOptions = {
+    quality: DEFAULT_QUALITY,
+    desktopOnly: false,
+    maxSections: DEFAULT_MAX_SECTIONS,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--url" && i + 1 < args.length) {
+      options.url = args[++i];
+    } else if (arg === "--routes") {
+      const routes: string[] = [];
+      while (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        routes.push(args[++i]);
+      }
+      if (routes.length > 0) options.routes = routes;
+    } else if (arg === "--quality" && i + 1 < args.length) {
+      const q = parseInt(args[++i], 10);
+      if (!isNaN(q)) options.quality = Math.max(1, Math.min(100, q));
+    } else if (arg === "--max-sections" && i + 1 < args.length) {
+      const m = parseInt(args[++i], 10);
+      if (!isNaN(m) && m > 0) options.maxSections = m;
+    } else if (arg === "--desktop-only") {
+      options.desktopOnly = true;
+    }
+  }
+
+  return options;
+}
+
+// ── Command ───────────────────────────────────────────────────────────────
+
+export async function designqc(cwd: string, args: string[]): Promise<void> {
+  const options = parseDesignQcArgs(args);
+
+  // ── Resolve server URL ────────────────────────────────────────────────
+  let serverUrl: string;
+
+  if (options.url) {
+    // Extract base URL from --url flag
+    try {
+      const parsed = new URL(options.url);
+      serverUrl = `${parsed.protocol}//${parsed.host}`;
+
+      // If --url has a path and no --routes, capture that single path
+      if (!options.routes && parsed.pathname !== "/") {
+        options.routes = [parsed.pathname];
+      }
+    } catch {
+      console.error(`[mink] Invalid URL: ${options.url}`);
+      process.exit(1);
+    }
+  } else {
+    console.log("[mink] Probing for running dev server...");
+    const found = await findRunningServer();
+
+    if (!found) {
+      const devCmd = detectDevCommand(cwd);
+      if (devCmd) {
+        console.error(
+          `[mink] No dev server detected. Start one with: ${devCmd}`
+        );
+      } else {
+        console.error(
+          "[mink] No dev server detected and no start command found in package.json."
+        );
+      }
+      process.exit(1);
+    }
+
+    serverUrl = found;
+    console.log(`[mink] Found dev server at ${serverUrl}`);
+  }
+
+  // ── Resolve routes ────────────────────────────────────────────────────
+  let routes: string[];
+
+  if (options.routes) {
+    routes = options.routes;
+    console.log(`[mink] Using specified routes: ${routes.join(", ")}`);
+  } else {
+    routes = detectRoutes(cwd);
+    console.log(`[mink] Detected ${routes.length} route(s): ${routes.join(", ")}`);
+  }
+
+  // ── Resolve viewports ─────────────────────────────────────────────────
+  const viewports: Viewport[] = options.desktopOnly
+    ? [DEFAULT_VIEWPORTS[0]]
+    : DEFAULT_VIEWPORTS;
+
+  console.log(
+    `[mink] Viewports: ${viewports.map((v) => `${v.name} (${v.width}×${v.height})`).join(", ")}`
+  );
+  console.log(`[mink] Quality: ${options.quality}, Max sections: ${options.maxSections}`);
+
+  // ── Capture ───────────────────────────────────────────────────────────
+  const outputDir = designCapturesDir(cwd);
+
+  console.log("[mink] Starting capture...");
+  const report = await captureAllRoutes(
+    routes,
+    serverUrl,
+    viewports,
+    options,
+    outputDir
+  );
+
+  // ── Save report ───────────────────────────────────────────────────────
+  atomicWriteJson(designReportPath(cwd), report);
+
+  // ── Summary ───────────────────────────────────────────────────────────
+  const totalSize = report.captures.reduce((sum, c) => sum + c.fileSize, 0);
+  const sizeKb = (totalSize / 1024).toFixed(1);
+
+  console.log("");
+  console.log(`[mink] Capture complete:`);
+  console.log(`  Screenshots: ${report.captures.length}`);
+  console.log(`  Total size:  ${sizeKb} KB`);
+  console.log(`  Output dir:  ${outputDir}`);
+  console.log(`  Report:      ${designReportPath(cwd)}`);
+
+  if (report.errors.length > 0) {
+    console.log(`  Errors:      ${report.errors.length}`);
+    for (const err of report.errors) {
+      console.log(`    • ${err.route} (${err.viewport}): ${err.error}`);
+    }
+  }
+
+  // Note any non-200 status codes
+  const errorPages = report.captures.filter(
+    (c) => c.statusCode >= 400
+  );
+  if (errorPages.length > 0) {
+    console.log("");
+    console.log(`[mink] Warning: ${errorPages.length} page(s) returned error status codes:`);
+    const seen = new Set<string>();
+    for (const c of errorPages) {
+      const key = `${c.route}:${c.statusCode}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      console.log(`    • ${c.route} → ${c.statusCode}`);
+    }
+  }
+}

package/src/commands/detect-waste.ts

@@ -0,0 +1,81 @@
+import { statSync } from "fs";
+import {
+  tokenLedgerPath,
+  fileIndexPath,
+  actionLogPath,
+  learningMemoryPath,
+} from "../core/paths";
+import { createEmptyLedger, isTokenLedger, saveLedger } from "../core/token-ledger";
+import { isFileIndex, createEmptyIndex } from "../core/index-store";
+import { safeReadLog } from "../core/action-log";
+import { safeReadJson } from "../core/fs-utils";
+import { runDetection } from "../core/waste-detection";
+import type { TokenLedger } from "../types/token-ledger";
+import type { FileIndex } from "../types/file-index";
+
+export function detectWaste(cwd: string): void {
+  const ledgerPath = tokenLedgerPath(cwd);
+  const idxPath = fileIndexPath(cwd);
+  const logPath = actionLogPath(cwd);
+  const lmPath = learningMemoryPath(cwd);
+
+  // Load and validate ledger — distinguish empty vs corrupted
+  const rawLedger = safeReadJson(ledgerPath);
+  let ledger: TokenLedger;
+
+  if (rawLedger === null) {
+    ledger = createEmptyLedger();
+  } else if (!isTokenLedger(rawLedger)) {
+    console.warn("[mink] Warning: corrupt token ledger, skipping waste detection");
+    return;
+  } else {
+    ledger = rawLedger;
+  }
+
+  // Load file index
+  const rawIndex = safeReadJson(idxPath);
+  let fileIndex: FileIndex;
+  if (rawIndex !== null && isFileIndex(rawIndex)) {
+    fileIndex = rawIndex;
+  } else {
+    fileIndex = createEmptyIndex();
+  }
+
+  // Load action log content
+  const actionLogContent = safeReadLog(logPath);
+
+  // Get learning memory mtime
+  let learningMemoryMtimeMs: number | null = null;
+  try {
+    learningMemoryMtimeMs = statSync(lmPath).mtimeMs;
+  } catch {
+    // File missing — will be flagged as stale
+  }
+
+  // Run detection
+  const flags = runDetection(
+    ledger,
+    fileIndex.entries,
+    fileIndex.header,
+    actionLogContent,
+    learningMemoryMtimeMs
+  );
+
+  // Store flags in ledger (replaces previous)
+  ledger.wasteFlags = flags;
+  saveLedger(ledgerPath, ledger);
+
+  // Output summary
+  if (flags.length === 0) {
+    console.log("[mink] Waste detection: no issues found.");
+  } else {
+    console.log(`[mink] Waste detection: ${flags.length} issue(s) found.`);
+    for (const flag of flags) {
+      console.log(`  - [${flag.pattern}] ${flag.description}`);
+      if (flag.estimatedTokensWasted > 0) {
+        console.log(`    Estimated waste: ~${flag.estimatedTokensWasted} tokens`);
+      }
+      console.log(`    Suggestion: ${flag.suggestion}`);
+    }
+  }
+}

package/src/commands/framework-advisor.ts

@@ -0,0 +1,52 @@
+import {
+  frameworkAdvisorPath,
+  frameworkAdvisorJsonPath,
+} from "../core/paths";
+import { atomicWriteJson, atomicWriteText } from "../core/fs-utils";
+import { buildKnowledge, generateKnowledgeMarkdown } from "../core/framework-advisor/generate";
+import { validateKnowledge } from "../core/framework-advisor/validate";
+
+export async function frameworkAdvisor(
+  cwd: string,
+  args: string[]
+): Promise<void> {
+  const isValidate = args.includes("--validate");
+  const isJson = args.includes("--json");
+
+  const knowledge = buildKnowledge();
+
+  if (isValidate) {
+    const result = validateKnowledge(knowledge);
+    if (result.valid) {
+      console.log("[mink] Framework advisor knowledge is valid.");
+      console.log(
+        `  ${knowledge.frameworks.length} frameworks, ${knowledge.decisionTree.length} decision nodes, ${knowledge.migrationPrompts.length} migration prompts`
+      );
+    } else {
+      console.error("[mink] Framework advisor validation failed:");
+      for (const err of result.errors) {
+        console.error(`  - ${err}`);
+      }
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (isJson) {
+    console.log(JSON.stringify(knowledge, null, 2));
+    return;
+  }
+
+  // Default: generate both files
+  const markdown = generateKnowledgeMarkdown(knowledge);
+
+  atomicWriteText(frameworkAdvisorPath(cwd), markdown);
+  atomicWriteJson(frameworkAdvisorJsonPath(cwd), knowledge);
+
+  console.log("[mink] Framework advisor knowledge generated:");
+  console.log(`  Markdown: ${frameworkAdvisorPath(cwd)}`);
+  console.log(`  JSON:     ${frameworkAdvisorJsonPath(cwd)}`);
+  console.log(
+    `  ${knowledge.frameworks.length} frameworks, ${knowledge.decisionTree.length} decision nodes, ${knowledge.migrationPrompts.length} migration prompts`
+  );
+}