@fureworks/scope 0.1.0 → 0.3.0

package/README.md

@@ -1,14 +1,8 @@
 # Scope
 
-**Personal ops CLI — focus on what matters.**
+**Scope tells you the 3 things that matter right now — and gives you permission to ignore everything else.**
 
-Scope reads your existing workflow (git repos, calendar, PRs) and tells you what actually needs your attention. It doesn't add to your workflow — it gives you clarity.
-
-## Why
-
-AI tools made you more capable. Which means more gets piled on. The bottleneck moved from *execution* to *prioritization and context switching*.
-
-Scope sits above your tools and helps you focus.
+A personal ops CLI for builders who juggle multiple repos, PRs, meetings, and issues. Scope reads your existing workflow signals and surfaces what needs attention. No manual input. No new accounts. No cloud.
 
 ## Install
 
@@ -16,77 +10,164 @@ Scope sits above your tools and helps you focus.
 npm install -g @fureworks/scope
 ```
 
+Requires Node.js 18+.
+
 ## Quick Start
 
 ```bash
-scope onboard     # Guided setup (1 minute)
-scope today       # What matters right now
+scope onboard    # guided first-time setup
+scope today      # what matters right now
+scope review     # end-of-day summary
 ```
 
-## Commands
+Or set up non-interactively (great for AI agents):
 
-```
-scope onboard              Guided first-time setup
-scope today                What needs your attention right now
-scope status               Overview of all watched projects
-scope switch <project>     Switch to a project context
-scope context              Show current project context
-scope review               End-of-day summary
-scope config               View/edit configuration
+```bash
+scope init
+scope config repos add ~/projects/my-app ~/projects/api
+scope config repos scan ~/work     # auto-discover git repos
+scope config calendar enable
+scope config projects add myproject --dir ~/projects/my-app
 ```
 
-## How It Works
+## What It Does
 
-Scope reads signals from your existing tools:
+Scope reads signals from tools you already use:
 
-- **Git** — uncommitted changes, stale branches, open PRs
-- **Google Calendar** — today's meetings, free blocks (via [gws](https://github.com/googleworkspace/cli))
-- **GitHub** — PR reviews waiting on you, failing CI
+- **Git** — uncommitted work, stale branches, recent activity
+- **GitHub** — open PRs, review requests, CI status, assigned issues
+- **Google Calendar** — meetings, free blocks (via `gws` CLI)
 
-It scores each item by urgency, staleness, and blocking potential, then shows you what matters:
+Then it scores and ranks everything using deterministic rules (no AI):
 
 ```
 $ scope today
 
+  Good morning. Here's what matters:
+
   NOW
   ───
-  🔴 Meeting: Team standup in 45 min
-  🔴 PR #8 on api-service — waiting on your review (3 days)
+  🔴 PR #8 on api-service (low context: no CI status)
+     auth migration — review requested, 3 days old
+     Why: Someone's waiting on your review. 3 days stale.
 
   TODAY
   ────
-  🟡 fureworks/scope — 3 uncommitted files, last touched 2h ago
-  🟡 PR #12 on fureworks.com — open 3 days, no review
+  🟡 fureworks/scope
+     3 uncommitted files, last touched 6h ago
+     Why: Uncommitted work for 6 hours. Commit or stash.
+
+  IGNORED
+  ───────
+  ✗ PR #2 on docs — Fresh, no one's waiting
+  ✗ Issue #12 on scope — Less than a week old, no priority label
+
+  Nothing else needs you today.
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `scope today` | Morning priorities — what needs attention right now |
+| `scope review` | End-of-day summary — what got done, what's carrying over |
+| `scope plan` | Weekly view — calendar density, PR backlog, best build days |
+| `scope status` | Overview of all watched projects |
+| `scope switch <project>` | Context switch between projects |
+| `scope context` | Show current project state |
+| `scope snooze <item> --until <date>` | Hide an item until a date |
+| `scope mute <item>` | Permanently hide an item |
+| `scope tune [key] [value]` | Adjust scoring weights |
+| `scope config repos\|calendar\|projects` | Manage configuration |
+| `scope init` | Initialize Scope |
+| `scope onboard` | Interactive guided setup |
+| `scope daemon start\|stop\|status` | Background signal checks |
+| `scope notifications` | View recent alerts |
+
+## How Scoring Works
+
+Each item gets a priority score based on measurable signals:
+
+```
+Score = (Time Pressure + Staleness + Blocking Potential + Effort Match) × Weight
+```
+
+- **Score ≥ 8** → 🔴 **NOW** — do these first (max 3 shown)
+- **Score 4–7** → 🟡 **TODAY** — fit these in (max 5 shown)
+- **Score < 4** → **IGNORED** — shown with reason, explicitly excluded
 
-  💡 2h free block after standup (14:00–16:00)
-     Good for: fureworks/scope (has pending work)
+Adjust weights with `scope tune`:
 
-  4 other items can wait → scope status
+```bash
+scope tune staleness 1.5   # stale items rank higher
+scope tune blocking 0.5    # reduce blocking urgency
+scope tune --reset          # restore defaults
 ```
 
-## Design Principles
+## Time Awareness
+
+`scope today` adjusts its tone based on when you run it:
 
-- **CLI-first, local-first** — your data stays on your machine
-- **Reads, doesn't create** — no new inputs required from you
-- **Opinionated output** — tells you what matters, not just lists stuff
-- **Degrades gracefully** — missing integrations skip quietly, never crash
-- **Open source** — MIT licensed
+- **Morning:** "Good morning. Here's what matters."
+- **Afternoon:** "3/5 from this morning done. 2 remaining."
+- **Evening:** "Run `scope review` to wrap up."
+
+## Weekly Planning
+
+```
+$ scope plan
+
+  THIS WEEK
+  ─────────
+  Mon  ████░░ 3 meetings, 2h free
+  Tue  ██░░░░ 1 meeting, 5h free ← best deep work day
+  Wed  █████░ 4 meetings, 1h free
+  Thu  ███░░░ 2 meetings, 4h free
+  Fri  █░░░░░ 0 meetings, 7h free
+
+  BACKLOG
+  ───────
+  3 PRs older than 1 week
+  2 issues approaching stale (>14 days)
+
+  💡 Tuesday + Friday are your best build days this week.
+```
 
 ## Prerequisites
 
-- Node.js 18+
-- Git
-- [GitHub CLI](https://cli.github.com/) (`gh`) — for PR data
-- [Google Workspace CLI](https://github.com/googleworkspace/cli) (`gws`) — for calendar (optional)
+Scope reads from external tools. All are optional — missing integrations reduce output but never crash.
 
-## Status
+| Tool | What it provides | Install |
+|------|-----------------|---------|
+| `gh` (GitHub CLI) | PRs, issues, CI status | [cli.github.com](https://cli.github.com/) |
+| `gws` (Google Workspace CLI) | Calendar events, free blocks | `npm i -g @googleworkspace/cli` |
 
-🚧 **v0.1 in development** — early but usable.
+## Best Practices
 
-## License
+See [WORKFLOW.md](./WORKFLOW.md) for habits that make Scope's output better — commit often, assign yourself, use labels, block focus time.
+
+## Philosophy
+
+- **Zero manual input.** Scope reads. It doesn't ask you to enter data.
+- **Confident exclusion.** The value isn't what's shown — it's what's hidden and why.
+- **Degraded mode is fine.** Only have git? Scope works. Add calendar? Better. Each integration is additive.
+- **CLI-first, local-first.** No accounts, no cloud, no tracking.
+- **No AI (v1).** Deterministic rules-based scoring. Transparent and predictable.
+
+## Data
 
-MIT — see [LICENSE](./LICENSE)
+Everything lives in `~/.scope/`:
 
----
+```
+~/.scope/
+├── config.toml          # configuration
+├── contexts/            # saved project contexts
+├── snapshots/           # daily snapshots (for review comparison)
+├── muted.json           # snoozed/muted items
+├── notifications.log    # notification history
+└── daemon.pid           # background process
+```
+
+## License
 
-*A [Fureworks](https://fureworks.com) project — works born from human touch.*
+MIT — [Fureworks](https://fureworks.com)

package/dist/cli/clean.d.ts

@@ -0,0 +1,7 @@
+interface CleanOptions {
+    json?: boolean;
+    dry?: boolean;
+}
+export declare function cleanCommand(options: CleanOptions): Promise<void>;
+export {};
+//# sourceMappingURL=clean.d.ts.map

package/dist/cli/clean.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean.d.ts","sourceRoot":"","sources":["../../src/cli/clean.ts"],"names":[],"mappings":"AAIA,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgEvE"}

package/dist/cli/clean.js

@@ -0,0 +1,49 @@
+import chalk from "chalk";
+import { loadConfig, configExists } from "../store/config.js";
+import { scanAllRepos } from "../sources/git.js";
+export async function cleanCommand(options) {
+    if (!configExists()) {
+        console.log(chalk.yellow("  Scope isn't set up yet. Run `scope onboard` to get started.\n"));
+        process.exit(1);
+    }
+    const config = loadConfig();
+    if (config.repos.length === 0) {
+        console.log(chalk.yellow("  No repos configured. Run `scope config repos add` to add some.\n"));
+        process.exit(1);
+    }
+    const signals = await scanAllRepos(config.repos);
+    const stale = [];
+    for (const signal of signals) {
+        for (const branch of signal.staleBranches) {
+            stale.push({ repo: signal.repo, branch });
+        }
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ stale }, null, 2));
+        return;
+    }
+    console.log("");
+    if (stale.length === 0) {
+        console.log(chalk.green("  ✓ No stale branches found. Repos are clean.\n"));
+        return;
+    }
+    console.log(chalk.bold("  STALE BRANCHES"));
+    console.log(chalk.dim("  ──────────────"));
+    const byRepo = new Map();
+    for (const { repo, branch } of stale) {
+        if (!byRepo.has(repo))
+            byRepo.set(repo, []);
+        byRepo.get(repo).push(branch);
+    }
+    for (const [repo, branches] of byRepo) {
+        console.log(`\n  ${chalk.bold(repo)}`);
+        for (const branch of branches) {
+            console.log(chalk.dim(`    ✗ ${branch}`));
+        }
+    }
+    console.log(chalk.dim(`\n  ${stale.length} stale branch${stale.length > 1 ? "es" : ""} across ${byRepo.size} repo${byRepo.size > 1 ? "s" : ""}.`));
+    if (!options.dry) {
+        console.log(chalk.dim("  To delete: git branch -d <branch> (in each repo)\n"));
+    }
+}
+//# sourceMappingURL=clean.js.map

package/dist/cli/clean.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean.js","sourceRoot":"","sources":["../../src/cli/clean.ts"],"names":[],"mappings":"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"}

package/dist/cli/config.d.ts

@@ -1,2 +1,9 @@
-export declare function configCommand(key?: string, value?: string): Promise<void>;
+import { Command } from "commander";
+type JsonOptions = {
+    json?: boolean;
+    dir?: string;
+};
+export declare function configCommand(key?: string, value?: string, options?: JsonOptions): Promise<void>;
+export declare function registerConfigCommand(program: Command): void;
+export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/cli/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"AAMA,wBAAsB,aAAa,CACjC,GAAG,CAAC,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAwDf"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,KAAK,WAAW,GAAG;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AA4HF,wBAAsB,aAAa,CACjC,GAAG,CAAC,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA+Cf;AAkND,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwE5D"}