@fureworks/scope 0.1.0

package/src/engine/prioritize.ts

@@ -0,0 +1,257 @@
+import { GitSignal, PRInfo } from "../sources/git.js";
+import { CalendarEvent, FreeBlock } from "../sources/calendar.js";
+import { IssueSignal } from "../sources/issues.js";
+
+export type Priority = "now" | "today" | "later";
+
+export interface ScoredItem {
+  priority: Priority;
+  score: number;
+  emoji: string;
+  label: string;
+  detail: string;
+  source: "git" | "calendar" | "pr" | "issue";
+}
+
+export interface PrioritizedOutput {
+  now: ScoredItem[];
+  today: ScoredItem[];
+  laterCount: number;
+  freeBlocks: FreeBlock[];
+  suggestions: string[];
+}
+
+function scorePR(pr: PRInfo, repoName: string): ScoredItem {
+  let score = 0;
+  const details: string[] = [];
+
+  // Staleness
+  if (pr.ageDays > 14) {
+    score += 9; // 2+ weeks = critical
+    details.push(`open ${Math.round(pr.ageDays)} days`);
+  } else if (pr.ageDays > 5) {
+    score += 7;
+    details.push(`open ${Math.round(pr.ageDays)} days`);
+  } else if (pr.ageDays > 2) {
+    score += 4;
+    details.push(`open ${Math.round(pr.ageDays)} days`);
+  }
+
+  // Blocking potential
+  if (pr.reviewRequested) {
+    score += 8;
+    details.push("review requested");
+  }
+  if (pr.ciStatus === "fail") {
+    score += 5;
+    details.push("CI failing");
+  }
+  if (pr.hasConflicts) {
+    score += 4;
+    details.push("has conflicts");
+  }
+
+  const priority: Priority = score >= 8 ? "now" : score >= 4 ? "today" : "later";
+
+  return {
+    priority,
+    score,
+    emoji: priority === "now" ? "🔴" : "🟡",
+    label: `PR #${pr.number} on ${repoName}`,
+    detail: `${pr.title} — ${details.join(", ")}`,
+    source: "pr",
+  };
+}
+
+function scoreRepoWork(signal: GitSignal): ScoredItem | null {
+  if (signal.uncommittedFiles === 0) return null;
+
+  let score = 0;
+  const details: string[] = [];
+
+  details.push(
+    `${signal.uncommittedFiles} uncommitted file${signal.uncommittedFiles > 1 ? "s" : ""}`
+  );
+
+  // Staleness of uncommitted work
+  const days = Math.round(signal.lastCommitAge / 24);
+  if (signal.lastCommitAge > 72) {
+    score += 9; // 3+ days uncommitted = NOW
+    details.push(`last commit ${days}d ago`);
+  } else if (signal.lastCommitAge > 24) {
+    score += 6;
+    details.push(`last commit ${days}d ago`);
+  } else if (signal.lastCommitAge > 4) {
+    score += 3;
+    details.push(`last touched ${Math.round(signal.lastCommitAge)}h ago`);
+  } else {
+    score += 1;
+  }
+
+  if (score < 2) return null; // Don't surface fresh uncommitted work
+
+  const priority: Priority = score >= 8 ? "now" : score >= 4 ? "today" : "later";
+
+  return {
+    priority,
+    score,
+    emoji: priority === "now" ? "🔴" : "🟡",
+    label: `${signal.repo}`,
+    detail: details.join(", "),
+    source: "git",
+  };
+}
+
+function scoreCalendarEvent(event: CalendarEvent): ScoredItem | null {
+  // Only surface upcoming events (not past ones)
+  if (event.minutesUntilStart < -15) return null;
+
+  let score = 0;
+
+  if (event.minutesUntilStart <= 60 && event.minutesUntilStart > 0) {
+    score += 10;
+  } else if (event.minutesUntilStart <= 0 && event.minutesUntilStart > -15) {
+    score += 10; // Happening now
+  } else {
+    score += 5;
+  }
+
+  const priority: Priority = score >= 8 ? "now" : "today";
+
+  let timeLabel: string;
+  if (event.minutesUntilStart <= 0) {
+    timeLabel = "happening now";
+  } else if (event.minutesUntilStart < 60) {
+    timeLabel = `in ${event.minutesUntilStart} min`;
+  } else {
+    const hours = Math.floor(event.minutesUntilStart / 60);
+    const mins = event.minutesUntilStart % 60;
+    timeLabel = `at ${event.startTime.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}`;
+    if (hours > 0) timeLabel += ` (${hours}h${mins > 0 ? `${mins}m` : ""} from now)`;
+  }
+
+  return {
+    priority,
+    score,
+    emoji: "🔴",
+    label: `Meeting: ${event.title}`,
+    detail: timeLabel,
+    source: "calendar",
+  };
+}
+
+function scoreIssue(issue: IssueSignal): ScoredItem | null {
+  let score = 0;
+  const details: string[] = [];
+
+  if (issue.ageDays > 14) {
+    score += 9;
+    details.push(`open ${Math.round(issue.ageDays)} days`);
+  } else if (issue.ageDays > 7) {
+    score += 7;
+    details.push(`open ${Math.round(issue.ageDays)} days`);
+  }
+
+  const hasPriorityLabel = issue.labels.some((label) =>
+    ["urgent", "critical", "bug"].includes(label.toLowerCase())
+  );
+  if (hasPriorityLabel) {
+    score += 3;
+    details.push("priority label");
+  }
+
+  if (score === 0) return null;
+
+  const priority: Priority = score >= 8 ? "now" : score >= 4 ? "today" : "later";
+  const labels = issue.labels.length > 0 ? ` [${issue.labels.join(", ")}]` : "";
+
+  return {
+    priority,
+    score,
+    emoji: "📋",
+    label: `Issue #${issue.number} on ${issue.repo}`,
+    detail: `${issue.title}${labels}${details.length > 0 ? ` — ${details.join(", ")}` : ""}`,
+    source: "issue",
+  };
+}
+
+export function prioritize(
+  gitSignals: GitSignal[],
+  calendarEvents: CalendarEvent[],
+  freeBlocks: FreeBlock[],
+  issues: IssueSignal[]
+): PrioritizedOutput {
+  const allItems: ScoredItem[] = [];
+
+  // Score calendar events
+  for (const event of calendarEvents) {
+    const scored = scoreCalendarEvent(event);
+    if (scored) allItems.push(scored);
+  }
+
+  // Score git repos
+  for (const signal of gitSignals) {
+    // Score uncommitted work
+    const repoItem = scoreRepoWork(signal);
+    if (repoItem) allItems.push(repoItem);
+
+    // Score PRs
+    for (const pr of signal.openPRs) {
+      allItems.push(scorePR(pr, signal.repo));
+    }
+  }
+
+  // Score issues
+  for (const issue of issues) {
+    const scored = scoreIssue(issue);
+    if (scored) allItems.push(scored);
+  }
+
+  // Sort by score descending
+  allItems.sort((a, b) => b.score - a.score);
+
+  // Cap output: max 3 NOW items, max 5 TODAY items. Rest goes to later.
+  const allNow = allItems.filter((i) => i.priority === "now");
+  const allToday = allItems.filter((i) => i.priority === "today");
+  const allLater = allItems.filter((i) => i.priority === "later");
+
+  const now = allNow.slice(0, 3);
+  const todayOverflow = allNow.slice(3);
+  const today = [...todayOverflow, ...allToday].slice(0, 5);
+  const laterCount =
+    allLater.length +
+    Math.max(0, todayOverflow.length + allToday.length - 5);
+
+  // Generate suggestions
+  const suggestions: string[] = [];
+  if (freeBlocks.length > 0) {
+    const biggestBlock = freeBlocks.reduce((a, b) =>
+      a.durationMinutes > b.durationMinutes ? a : b
+    );
+    const blockStart = biggestBlock.start.toLocaleTimeString([], {
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+    const blockEnd = biggestBlock.end.toLocaleTimeString([], {
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+    const hours = Math.floor(biggestBlock.durationMinutes / 60);
+    const mins = biggestBlock.durationMinutes % 60;
+    const durationStr = hours > 0 ? `${hours}h${mins > 0 ? `${mins}m` : ""}` : `${mins}m`;
+
+    // Find a good item to suggest for this block
+    const deepWorkItem = today.find((i) => i.source === "git");
+    if (deepWorkItem) {
+      suggestions.push(
+        `${durationStr} free block (${blockStart}–${blockEnd}). Good for: ${deepWorkItem.label}`
+      );
+    } else {
+      suggestions.push(
+        `${durationStr} free block available (${blockStart}–${blockEnd})`
+      );
+    }
+  }
+
+  return { now, today, laterCount, freeBlocks, suggestions };
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { todayCommand } from "./cli/today.js";
+import { switchCommand } from "./cli/switch.js";
+import { contextCommand } from "./cli/context.js";
+import { statusCommand } from "./cli/status.js";
+import { onboardCommand } from "./cli/onboard.js";
+import { configCommand } from "./cli/config.js";
+import { daemonCommand } from "./cli/daemon.js";
+
+const program = new Command();
+
+program
+  .name("scope")
+  .description("Personal ops CLI — focus on what matters.")
+  .version("0.1.0");
+
+program
+  .command("today")
+  .description("What needs your attention right now")
+  .option("--no-calendar", "Skip calendar data")
+  .option("--json", "Output as JSON")
+  .action(todayCommand);
+
+program
+  .command("onboard")
+  .description("Guided first-time setup")
+  .action(onboardCommand);
+
+program
+  .command("switch <project>")
+  .description("Switch to a project context")
+  .action(switchCommand);
+
+program
+  .command("context")
+  .description("Show current project context")
+  .option("--edit", "Open scratchpad in $EDITOR")
+  .action(contextCommand);
+
+program
+  .command("status")
+  .description("Overview of all watched projects")
+  .option("--json", "Output as JSON")
+  .action(statusCommand);
+
+program
+  .command("config [key] [value]")
+  .description("View or edit configuration")
+  .action(configCommand);
+
+program
+  .command("daemon <action>")
+  .description("Manage background signal checks (start|stop|status)")
+  .action(daemonCommand);
+
+program.parse();

package/src/notifications/index.ts

@@ -0,0 +1,42 @@
+import { appendFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { ensureScopeDir, getScopeDir } from "../store/config.js";
+
+function commandExists(command: string): boolean {
+  const check = spawnSync("which", [command], { stdio: "pipe" });
+  return check.status === 0;
+}
+
+function fallbackNotify(title: string, body: string): void {
+  ensureScopeDir();
+  const logPath = join(getScopeDir(), "notifications.log");
+  appendFileSync(logPath, `[${new Date().toISOString()}] ${title}: ${body}\n`, "utf-8");
+}
+
+export function notify(title: string, body: string): void {
+  try {
+    if (process.platform === "linux") {
+      if (commandExists("notify-send")) {
+        const result = spawnSync("notify-send", [title, body], { stdio: "pipe" });
+        if (result.status === 0) return;
+      }
+      fallbackNotify(title, body);
+      return;
+    }
+
+    if (process.platform === "darwin") {
+      const escapedTitle = title.replace(/"/g, '\\"');
+      const escapedBody = body.replace(/"/g, '\\"');
+      const script = `display notification "${escapedBody}" with title "${escapedTitle}"`;
+      const result = spawnSync("osascript", ["-e", script], { stdio: "pipe" });
+      if (result.status === 0) return;
+      fallbackNotify(title, body);
+      return;
+    }
+
+    fallbackNotify(title, body);
+  } catch {
+    fallbackNotify(title, body);
+  }
+}

package/src/sources/calendar.ts

@@ -0,0 +1,170 @@
+export interface CalendarEvent {
+  title: string;
+  startTime: Date;
+  endTime: Date;
+  minutesUntilStart: number;
+}
+
+export interface CalendarSignal {
+  events: CalendarEvent[];
+  freeBlocks: FreeBlock[];
+}
+
+export interface FreeBlock {
+  start: Date;
+  end: Date;
+  durationMinutes: number;
+}
+
+export async function getCalendarToday(): Promise<CalendarSignal | null> {
+  try {
+    const { execSync } = await import("node:child_process");
+
+    // Check if gws is installed
+    try {
+      execSync("which gws", { stdio: "pipe" });
+    } catch {
+      return null;
+    }
+
+    // Get today's events via gws calendar +agenda --today
+    const result = execSync(
+      `gws calendar +agenda --today --format json 2>/dev/null`,
+      {
+        encoding: "utf-8",
+        timeout: 15000,
+        stdio: ["pipe", "pipe", "pipe"],
+      }
+    );
+
+    let items: Array<{
+      summary?: string;
+      title?: string;
+      start?: string | { dateTime?: string; date?: string };
+      end?: string | { dateTime?: string; date?: string };
+      startTime?: string;
+      endTime?: string;
+    }>;
+
+    try {
+      const data = JSON.parse(result);
+      // gws may return array directly or nested in a field
+      items = Array.isArray(data) ? data : data.items || data.events || [];
+    } catch {
+      // Try parsing as NDJSON (one JSON object per line)
+      items = result
+        .trim()
+        .split("\n")
+        .filter((line) => line.trim())
+        .flatMap((line) => {
+          try {
+            const parsed = JSON.parse(line);
+            // Could be a wrapper with items array or a single event
+            if (Array.isArray(parsed)) return parsed;
+            if (parsed.items) return parsed.items;
+            if (parsed.events) return parsed.events;
+            return [parsed];
+          } catch {
+            return [];
+          }
+        });
+    }
+
+    const now = Date.now();
+
+    const events: CalendarEvent[] = items
+      .map((item) => {
+        // Handle various gws output formats
+        const startStr =
+          typeof item.start === "string"
+            ? item.start
+            : item.start?.dateTime || item.startTime;
+        const endStr =
+          typeof item.end === "string"
+            ? item.end
+            : item.end?.dateTime || item.endTime;
+        const title = item.summary || item.title || "Untitled event";
+
+        if (!startStr) return null;
+
+        const startTime = new Date(startStr);
+        const endTime = endStr ? new Date(endStr) : new Date(startTime.getTime() + 60 * 60 * 1000);
+
+        if (isNaN(startTime.getTime())) return null;
+
+        return {
+          title,
+          startTime,
+          endTime,
+          minutesUntilStart: Math.round(
+            (startTime.getTime() - now) / (1000 * 60)
+          ),
+        };
+      })
+      .filter((e): e is CalendarEvent => e !== null)
+      .sort((a, b) => a.startTime.getTime() - b.startTime.getTime());
+
+    // Calculate free blocks (between events, min 30 min)
+    const freeBlocks = calculateFreeBlocks(events, new Date());
+
+    return { events, freeBlocks };
+  } catch {
+    return null;
+  }
+}
+
+function calculateFreeBlocks(
+  events: CalendarEvent[],
+  today: Date
+): FreeBlock[] {
+  const blocks: FreeBlock[] = [];
+  const now = new Date();
+
+  // Working hours: 9am to 6pm
+  const workStart = new Date(today);
+  workStart.setHours(9, 0, 0, 0);
+  const workEnd = new Date(today);
+  workEnd.setHours(18, 0, 0, 0);
+
+  // Start from now or work start, whichever is later
+  let cursor = new Date(Math.max(now.getTime(), workStart.getTime()));
+
+  const futureEvents = events.filter(
+    (e) => e.endTime.getTime() > cursor.getTime()
+  );
+
+  for (const event of futureEvents) {
+    if (event.startTime.getTime() > cursor.getTime()) {
+      const gapMinutes = Math.round(
+        (event.startTime.getTime() - cursor.getTime()) / (1000 * 60)
+      );
+      if (gapMinutes >= 30) {
+        blocks.push({
+          start: new Date(cursor),
+          end: new Date(event.startTime),
+          durationMinutes: gapMinutes,
+        });
+      }
+    }
+    // Move cursor past this event
+    if (event.endTime.getTime() > cursor.getTime()) {
+      cursor = new Date(event.endTime);
+    }
+  }
+
+  // Check for free time after last event until end of work
+  if (cursor.getTime() < workEnd.getTime()) {
+    const gapMinutes = Math.round(
+      (workEnd.getTime() - cursor.getTime()) / (1000 * 60)
+    );
+    if (gapMinutes >= 30) {
+      blocks.push({
+        start: new Date(cursor),
+        end: new Date(workEnd),
+        durationMinutes: gapMinutes,
+      });
+    }
+  }
+
+  return blocks;
+}

package/src/sources/git.ts

@@ -0,0 +1,168 @@
+import { simpleGit, SimpleGit } from "simple-git";
+import { existsSync } from "node:fs";
+
+export interface GitSignal {
+  repo: string;
+  branch: string;
+  uncommittedFiles: number;
+  lastCommitAge: number; // hours since last commit
+  staleBranches: string[]; // branches untouched > 3 days
+  openPRs: PRInfo[];
+}
+
+export interface PRInfo {
+  number: number;
+  title: string;
+  url: string;
+  ageDays: number;
+  reviewRequested: boolean;
+  ciStatus: "pass" | "fail" | "pending" | "unknown";
+  hasConflicts: boolean;
+}
+
+export async function scanRepo(repoPath: string): Promise<GitSignal | null> {
+  if (!existsSync(repoPath)) {
+    return null;
+  }
+
+  const git: SimpleGit = simpleGit(repoPath);
+
+  try {
+    const isRepo = await git.checkIsRepo();
+    if (!isRepo) return null;
+
+    // Get current branch
+    const branchInfo = await git.branch();
+    const branch = branchInfo.current;
+
+    // Get uncommitted changes
+    const status = await git.status();
+    const uncommittedFiles =
+      status.modified.length +
+      status.not_added.length +
+      status.created.length +
+      status.deleted.length;
+
+    // Get last commit time
+    let lastCommitAge = 0;
+    try {
+      const log = await git.log({ maxCount: 1 });
+      if (log.latest?.date) {
+        const lastCommitDate = new Date(log.latest.date);
+        lastCommitAge =
+          (Date.now() - lastCommitDate.getTime()) / (1000 * 60 * 60);
+      }
+    } catch {
+      // No commits yet
+    }
+
+    // Get stale branches (untouched > 3 days)
+    const staleBranches: string[] = [];
+    try {
+      const branches = await git.branch(["-a", "--sort=-committerdate"]);
+      const threeDaysAgo = Date.now() - 3 * 24 * 60 * 60 * 1000;
+
+      for (const branchName of branches.all) {
+        if (branchName === branch) continue;
+        if (branchName.startsWith("remotes/")) continue;
+
+        try {
+          const branchLog = await git.log({
+            maxCount: 1,
+            from: branchName,
+          });
+          if (branchLog.latest?.date) {
+            const branchDate = new Date(branchLog.latest.date);
+            if (branchDate.getTime() < threeDaysAgo) {
+              staleBranches.push(branchName);
+            }
+          }
+        } catch {
+          // Skip branches we can't read
+        }
+      }
+    } catch {
+      // Branch listing failed
+    }
+
+    // Get open PRs via gh CLI
+    const openPRs = await getOpenPRs(repoPath);
+
+    const repoName = repoPath.split("/").pop() || repoPath;
+
+    return {
+      repo: repoName,
+      branch,
+      uncommittedFiles,
+      lastCommitAge,
+      staleBranches: staleBranches.slice(0, 5), // Cap at 5
+      openPRs,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function getOpenPRs(repoPath: string): Promise<PRInfo[]> {
+  try {
+    const { execSync } = await import("node:child_process");
+    const result = execSync(
+      `gh pr list --json number,title,url,createdAt,reviewRequests,statusCheckRollup,mergeable --limit 10`,
+      {
+        cwd: repoPath,
+        encoding: "utf-8",
+        timeout: 10000,
+        stdio: ["pipe", "pipe", "pipe"],
+      }
+    );
+
+    const prs = JSON.parse(result) as Array<{
+      number: number;
+      title: string;
+      url: string;
+      createdAt: string;
+      reviewRequests: Array<{ login?: string }>;
+      statusCheckRollup: Array<{ conclusion: string }> | null;
+      mergeable: string;
+    }>;
+
+    return prs.map((pr) => {
+      const ageDays =
+        (Date.now() - new Date(pr.createdAt).getTime()) /
+        (1000 * 60 * 60 * 24);
+
+      let ciStatus: PRInfo["ciStatus"] = "unknown";
+      if (pr.statusCheckRollup && pr.statusCheckRollup.length > 0) {
+        const hasFailure = pr.statusCheckRollup.some(
+          (c) => c.conclusion === "FAILURE"
+        );
+        const allSuccess = pr.statusCheckRollup.every(
+          (c) => c.conclusion === "SUCCESS"
+        );
+        if (hasFailure) ciStatus = "fail";
+        else if (allSuccess) ciStatus = "pass";
+        else ciStatus = "pending";
+      }
+
+      return {
+        number: pr.number,
+        title: pr.title,
+        url: pr.url,
+        ageDays: Math.round(ageDays * 10) / 10,
+        reviewRequested: pr.reviewRequests.length > 0,
+        ciStatus,
+        hasConflicts: pr.mergeable === "CONFLICTING",
+      };
+    });
+  } catch {
+    // gh CLI not available or not in a repo with remote
+    return [];
+  }
+}
+
+export async function scanAllRepos(
+  repoPaths: string[]
+): Promise<GitSignal[]> {
+  const results = await Promise.all(repoPaths.map(scanRepo));
+  return results.filter((r): r is GitSignal => r !== null);
+}