@drewpayment/mink 0.1.0

package/src/types/design-eval.ts

@@ -0,0 +1,64 @@
+// ── Design Evaluation Types (Spec 13) ─────────────────────────────────────
+
+export interface Viewport {
+  name: "desktop" | "mobile";
+  width: number;
+  height: number;
+}
+
+export interface DesignQcOptions {
+  url?: string;
+  routes?: string[];
+  quality: number;
+  desktopOnly: boolean;
+  maxSections: number;
+}
+
+export interface CaptureResult {
+  route: string;
+  viewport: string;
+  section: number;
+  totalSections: number;
+  filePath: string;
+  fileName: string;
+  fileSize: number;
+  pageHeight: number;
+  statusCode: number;
+  timestamp: string;
+}
+
+export interface DesignEvalReport {
+  capturedAt: string;
+  serverUrl: string;
+  routes: string[];
+  viewports: Viewport[];
+  quality: number;
+  captures: CaptureResult[];
+  errors: Array<{ route: string; viewport: string; error: string }>;
+}
+
+// ── Defaults ──────────────────────────────────────────────────────────────
+
+export const DEFAULT_VIEWPORTS: Viewport[] = [
+  { name: "desktop", width: 1440, height: 900 },
+  { name: "mobile", width: 375, height: 812 },
+];
+
+export const DEFAULT_QUALITY = 70;
+export const DEFAULT_MAX_SECTIONS = 8;
+
+export const DEFAULT_PROBE_PORTS = [
+  3000, 3001, 4000, 5000, 5173, 8000, 8080,
+];
+
+// ── Type Guard ────────────────────────────────────────────────────────────
+
+export function isDesignEvalReport(v: unknown): v is DesignEvalReport {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "capturedAt" in v &&
+    "captures" in v &&
+    Array.isArray((v as DesignEvalReport).captures)
+  );
+}

package/src/types/file-index.ts

@@ -0,0 +1,38 @@
+export interface FileIndexHeader {
+  lastScanTimestamp: string;
+  totalFiles: number;
+  lifetimeHits: number;
+  lifetimeMisses: number;
+}
+
+export interface FileIndexEntry {
+  filePath: string;
+  description: string;
+  estimatedTokens: number;
+  lastModified: string;
+  lastIndexed: string;
+}
+
+export interface FileIndex {
+  header: FileIndexHeader;
+  entries: Record<string, FileIndexEntry>;
+}
+
+export interface ProjectConfig {
+  excludePatterns?: string[];
+  maxFiles?: number;
+  learningMemoryTokenBudget?: number;
+  actionLogMaxEntries?: number;
+  actionLogRetentionDays?: number;
+}
+
+export interface StalenessReport {
+  missingFromIndex: string[];
+  orphanedEntries: string[];
+  isStale: boolean;
+}
+
+export interface ScannedFile {
+  relativePath: string;
+  mtimeMs: number;
+}

package/src/types/framework-advisor.ts

@@ -0,0 +1,97 @@
+// ── Framework Advisor Types (Spec 14) ─────────────────────────────────────
+
+export type CssApproach =
+  | "utility-first"
+  | "css-in-js"
+  | "css-modules"
+  | "scoped"
+  | "traditional"
+  | "hybrid";
+
+export type BundleSize = "tiny" | "small" | "medium" | "large";
+
+export type LearningCurve = "low" | "moderate" | "steep";
+
+export type AccessibilityRating = "basic" | "good" | "excellent";
+
+export type TypescriptSupport = "native" | "supported" | "limited";
+
+export interface FrameworkEntry {
+  id: string;
+  name: string;
+  description: string;
+  cssApproach: CssApproach;
+  darkModeSupport: boolean;
+  accessibilityRating: AccessibilityRating;
+  bundleSize: BundleSize;
+  learningCurve: LearningCurve;
+  typescriptSupport: TypescriptSupport;
+  designTokens: boolean;
+  ecosystem: string;
+  bestFor: string[];
+  limitations: string[];
+  officialUrl: string;
+}
+
+export interface DecisionTreeOption {
+  label: string;
+  value: string;
+  nextNodeId: string | null;
+  recommends?: string[];
+}
+
+export interface DecisionTreeNode {
+  id: string;
+  question: string;
+  options: DecisionTreeOption[];
+}
+
+export const MIGRATION_SECTION_KEYS = [
+  "install",
+  "configure",
+  "migrate-components",
+  "migrate-styles",
+  "gotchas",
+  "verification",
+] as const;
+
+export type MigrationSectionKey = (typeof MIGRATION_SECTION_KEYS)[number];
+
+export interface MigrationPromptSection {
+  key: MigrationSectionKey;
+  content: string;
+}
+
+export interface MigrationPrompt {
+  frameworkId: string;
+  sections: MigrationPromptSection[];
+}
+
+export interface FrameworkAdvisorKnowledge {
+  version: string;
+  generatedAt: string;
+  frameworks: FrameworkEntry[];
+  decisionTree: DecisionTreeNode[];
+  migrationPrompts: MigrationPrompt[];
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+// ── Type Guard ────────────────────────────────────────────────────────────
+
+export function isFrameworkAdvisorKnowledge(
+  v: unknown
+): v is FrameworkAdvisorKnowledge {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "version" in v &&
+    "frameworks" in v &&
+    "decisionTree" in v &&
+    "migrationPrompts" in v &&
+    Array.isArray((v as FrameworkAdvisorKnowledge).frameworks)
+  );
+}

package/src/types/hook-input.ts

@@ -0,0 +1,27 @@
+export interface PreToolUseInput {
+  tool_name: string;
+  tool_input: {
+    file_path?: string;
+    // Write tool
+    content?: string;
+    // Edit tool
+    old_string?: string;
+    new_string?: string;
+  };
+}
+
+export interface PostToolUseInput {
+  tool_name: string;
+  tool_input: {
+    file_path?: string;
+    // Write tool
+    content?: string;
+    // Edit tool
+    old_string?: string;
+    new_string?: string;
+  };
+  tool_output?: {
+    content?: string;
+    [key: string]: unknown;
+  };
+}

package/src/types/learning-memory.ts

@@ -0,0 +1,36 @@
+export type SectionName =
+  | "User Preferences"
+  | "Key Learnings"
+  | "Do-Not-Repeat"
+  | "Decision Log";
+
+export interface LearningMemory {
+  projectName: string;
+  sections: Record<SectionName, string[]>;
+}
+
+export interface ExtractedPattern {
+  type: "literal" | "word-boundary";
+  pattern: string;
+  sourceEntry: string;
+}
+
+export interface PatternMatch {
+  pattern: ExtractedPattern;
+  matchedText: string;
+  index: number;
+}
+
+export interface ReflectionResult {
+  beforeTokens: number;
+  afterTokens: number;
+  mergedCount: number;
+  trimmedCount: number;
+  withinBudget: boolean;
+}
+
+export interface SeedInfo {
+  projectName: string;
+  description: string;
+  frameworks: string[];
+}

package/src/types/scheduler.ts

@@ -0,0 +1,82 @@
+// ── Cron ────────────────────────────────────────────────────────────────────
+
+export interface CronSchedule {
+  minute: number[];      // 0-59
+  hour: number[];        // 0-23
+  dayOfMonth: number[];  // 1-31
+  month: number[];       // 1-12
+  dayOfWeek: number[];   // 0-6 (0=Sunday)
+}
+
+// ── Task Definition ─────────────────────────────────────────────────────────
+
+export type ActionType = "function" | "ai-cli";
+
+export type TaskStatus = "idle" | "running" | "retrying" | "dead-lettered";
+
+export interface RetryPolicy {
+  maxAttempts: number;
+  baseDelayMs: number;
+}
+
+export interface TaskDefinition {
+  id: string;
+  name: string;
+  description: string;
+  schedule: string;
+  actionType: ActionType;
+  enabled: boolean;
+  retryPolicy: RetryPolicy;
+  timeoutMs: number;
+}
+
+// ── Task Execution State ────────────────────────────────────────────────────
+
+export interface TaskRunRecord {
+  taskId: string;
+  lastRunAt: string | null;
+  lastSuccessAt: string | null;
+  lastFailureAt: string | null;
+  nextRunAt: string;
+  status: TaskStatus;
+  consecutiveFailures: number;
+  currentAttempt: number;
+}
+
+// ── Dead Letter ─────────────────────────────────────────────────────────────
+
+export interface DeadLetterEntry {
+  taskId: string;
+  deadLetteredAt: string;
+  failureTimestamps: string[];
+  errorMessages: string[];
+  attemptCount: number;
+}
+
+// ── Health ───────────────────────────────────────────────────────────────────
+
+export interface HealthStatus {
+  pid: number;
+  startedAt: string;
+  lastHeartbeatAt: string;
+  uptimeMs: number;
+  activeTasks: string[];
+  deadLetterCount: number;
+  taskCount: number;
+}
+
+// ── Scheduler Manifest (persisted state) ────────────────────────────────────
+
+export interface SchedulerManifest {
+  tasks: TaskRunRecord[];
+  deadLetterQueue: DeadLetterEntry[];
+  lastHeartbeat: string;
+}
+
+// ── PID File ────────────────────────────────────────────────────────────────
+
+export interface PidFileData {
+  pid: number;
+  startedAt: string;
+  projectCwd: string;
+}

package/src/types/session.ts

@@ -0,0 +1,50 @@
+export interface FileRead {
+  readCount: number;
+  estimatedTokens: number;
+  firstReadAt: string; // ISO 8601 UTC
+}
+
+export interface WriteEntry {
+  filePath: string;
+  action: "create" | "edit";
+  estimatedTokens: number;
+  timestamp: string; // ISO 8601 UTC
+}
+
+export interface SessionCounters {
+  fileIndexHits: number;
+  fileIndexMisses: number;
+  repeatedReadWarnings: number;
+  learnedRuleWarnings: number;
+}
+
+export interface SessionState {
+  sessionId: string;
+  startTimestamp: string; // ISO 8601 UTC
+  stopCount: number;
+  reads: Record<string, FileRead>;
+  writes: WriteEntry[];
+  counters: SessionCounters;
+}
+
+export interface SessionSummary {
+  sessionId: string;
+  startTimestamp: string;
+  endTimestamp: string;
+  reads: Array<{ filePath: string } & FileRead>;
+  writes: WriteEntry[];
+  totals: {
+    readCount: number;
+    writeCount: number;
+    estimatedTokens: number;
+    repeatedReads: number;
+    fileIndexHits: number;
+    fileIndexMisses: number;
+  };
+  estimatedSavings: number;
+}
+
+export interface SessionFinalizer {
+  appendSession(summary: SessionSummary): void;
+  updateSession(summary: SessionSummary): void;
+}

package/src/types/token-ledger.ts

@@ -0,0 +1,43 @@
+export interface LifetimeCounters {
+  totalTokens: number;
+  totalReads: number;
+  totalWrites: number;
+  totalSessions: number;
+  totalFileIndexHits: number;
+  totalFileIndexMisses: number;
+  totalRepeatedReads: number;
+  totalEstimatedSavings: number;
+}
+
+export interface LedgerSession {
+  sessionId: string;
+  startTimestamp: string;
+  endTimestamp: string;
+  reads: Array<{
+    filePath: string;
+    estimatedTokens: number;
+    readCount: number;
+  }>;
+  writes: Array<{
+    filePath: string;
+    estimatedTokens: number;
+    action: "create" | "edit";
+  }>;
+  totals: {
+    readCount: number;
+    writeCount: number;
+    estimatedTokens: number;
+    repeatedReads: number;
+    fileIndexHits: number;
+    fileIndexMisses: number;
+  };
+  estimatedSavings: number;
+}
+
+import type { WasteFlag } from "./waste-detection";
+
+export interface TokenLedger {
+  lifetime: LifetimeCounters;
+  sessions: LedgerSession[];
+  wasteFlags?: WasteFlag[];
+}

package/src/types/waste-detection.ts

@@ -0,0 +1,21 @@
+export type WastePattern =
+  | "repeated-reads"
+  | "missed-index-opportunity"
+  | "action-log-bloat"
+  | "learning-memory-staleness"
+  | "index-miss-rate";
+
+export interface WasteFlag {
+  pattern: WastePattern;
+  description: string;
+  estimatedTokensWasted: number;
+  suggestion: string;
+  detectedAt: string;
+}
+
+export interface DetectionConfig {
+  actionLogBloatThreshold: number;
+  learningMemoryStaleDays: number;
+  indexMissRateThreshold: number;
+  missedIndexMinTokens: number;
+}