@fureworks/scope 0.1.0 → 0.2.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/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"}

package/dist/cli/config.js

@@ -1,54 +1,380 @@
-import chalk from "chalk";
-import { loadConfig, configExists } from "../store/config.js";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync, } from "node:fs";
 import { homedir } from "node:os";
-export async function configCommand(key, value) {
-    if (!configExists()) {
-        console.log(chalk.yellow("\n  No config found. Run `scope onboard` to get started.\n"));
+import { isAbsolute, join, resolve } from "node:path";
+import { configExists, loadConfig, saveConfig } from "../store/config.js";
+function output(json, payload, text) {
+    if (json) {
+        console.log(JSON.stringify(payload));
         return;
     }
-    // If no args, show config file contents
+    console.log(text);
+}
+function fail(json, message, payload) {
+    if (json) {
+        console.log(JSON.stringify({
+            ok: false,
+            error: message,
+            ...(payload && typeof payload === "object" ? payload : {}),
+        }));
+    }
+    else {
+        console.error(message);
+    }
+    process.exitCode = 1;
+}
+function expandPath(input) {
+    if (input === "~") {
+        return homedir();
+    }
+    if (input.startsWith("~/")) {
+        return join(homedir(), input.slice(2));
+    }
+    return input;
+}
+function toAbsolutePath(input) {
+    const expanded = expandPath(input);
+    return isAbsolute(expanded) ? expanded : resolve(expanded);
+}
+function parseScalar(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    const parsedNumber = Number(value);
+    if (!Number.isNaN(parsedNumber) && value.trim() !== "") {
+        return parsedNumber;
+    }
+    return value;
+}
+function setConfigValue(config, key, value) {
+    const parts = key.split(".").filter(Boolean);
+    if (parts.length === 0) {
+        return false;
+    }
+    const parsedValue = parseScalar(value);
+    let cursor = config;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        const part = parts[i];
+        const existing = cursor[part];
+        if (!existing || typeof existing !== "object") {
+            cursor[part] = {};
+        }
+        cursor = cursor[part];
+    }
+    cursor[parts[parts.length - 1]] = parsedValue;
+    return true;
+}
+function runCommand(command) {
+    try {
+        const stdout = execSync(command, { stdio: "pipe", encoding: "utf8" });
+        return { ok: true, output: stdout.trim() };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, output: message.trim() };
+    }
+}
+function collectGitRepos(rootDir) {
+    const repos = new Set();
+    const queue = [rootDir];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (!current)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(current);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const fullPath = join(current, entry);
+            let stats;
+            try {
+                stats = lstatSync(fullPath);
+            }
+            catch {
+                continue;
+            }
+            if (stats.isSymbolicLink()) {
+                continue;
+            }
+            if (entry === ".git" && stats.isDirectory()) {
+                repos.add(current);
+                continue;
+            }
+            if (stats.isDirectory() && entry !== ".git") {
+                queue.push(fullPath);
+            }
+        }
+    }
+    return [...repos];
+}
+export async function configCommand(key, value, options = {}) {
+    const json = Boolean(options.json);
     if (!key) {
+        if (json) {
+            output(true, { ok: true, config: loadConfig() }, "");
+            return;
+        }
+        if (!configExists()) {
+            console.log("No config found");
+            return;
+        }
         const configPath = join(homedir(), ".scope", "config.toml");
         try {
-            const content = readFileSync(configPath, "utf-8");
-            console.log("");
-            console.log(chalk.bold("  ~/.scope/config.toml"));
-            console.log(chalk.dim("  ─────────────────────\n"));
-            console.log(content
-                .split("\n")
-                .map((line) => `  ${line}`)
-                .join("\n"));
-            console.log("");
+            const content = readFileSync(configPath, "utf-8").trimEnd();
+            console.log(content);
         }
         catch {
-            console.log(chalk.yellow("\n  Could not read config file.\n"));
-        }
-        return;
-    }
-    // Subcommands
-    switch (key) {
-        case "git":
-            console.log(chalk.dim("\n  To manage repos, edit ~/.scope/config.toml"));
-            console.log(chalk.dim("  or re-run: scope onboard\n"));
-            break;
-        case "calendar":
-            console.log(chalk.dim("\n  To set up calendar, install gws:"));
-            console.log(chalk.dim("  npm install -g @googleworkspace/cli"));
-            console.log(chalk.dim("  Then re-run: scope onboard\n"));
-            break;
-        case "projects":
-            const config = loadConfig();
-            console.log(chalk.bold("\n  Projects:"));
-            for (const [name, project] of Object.entries(config.projects)) {
-                console.log(`  ${name} → ${project.path}`);
+            fail(false, "Could not read config file");
+        }
+        return;
+    }
+    if (value === undefined) {
+        const config = loadConfig();
+        const parts = key.split(".").filter(Boolean);
+        let cursor = config;
+        for (const part of parts) {
+            if (!cursor || typeof cursor !== "object" || !(part in cursor)) {
+                fail(json, `Unknown config key: ${key}`);
+                return;
             }
-            console.log(chalk.dim("\n  Edit: ~/.scope/config.toml\n"));
-            break;
-        default:
-            console.log(chalk.yellow(`\n  Unknown config key: ${key}`));
-            console.log(chalk.dim("  Available: git, calendar, projects\n"));
+            cursor = cursor[part];
+        }
+        output(json, { ok: true, key, value: cursor }, `${key}=${String(cursor)}`);
+        return;
+    }
+    const config = loadConfig();
+    const updated = setConfigValue(config, key, value);
+    if (!updated) {
+        fail(json, `Invalid config key: ${key}`);
+        return;
+    }
+    saveConfig(config);
+    output(json, { ok: true, key, value: parseScalar(value) }, "Config updated");
+}
+async function reposAdd(paths, options) {
+    const json = Boolean(options.json);
+    const config = loadConfig();
+    const existing = new Set(config.repos);
+    const added = [];
+    const invalid = [];
+    for (const rawPath of paths) {
+        const absolutePath = toAbsolutePath(rawPath);
+        if (!existsSync(absolutePath)) {
+            invalid.push(absolutePath);
+            continue;
+        }
+        let isDirectory = false;
+        try {
+            isDirectory = statSync(absolutePath).isDirectory();
+        }
+        catch {
+            invalid.push(absolutePath);
+            continue;
+        }
+        if (!isDirectory) {
+            invalid.push(absolutePath);
+            continue;
+        }
+        if (!existing.has(absolutePath)) {
+            existing.add(absolutePath);
+            added.push(absolutePath);
+        }
+    }
+    if (invalid.length > 0) {
+        fail(json, `Invalid repo path(s): ${invalid.join(", ")}`, { invalid });
+        return;
+    }
+    if (added.length > 0) {
+        config.repos = [...existing];
+        saveConfig(config);
+    }
+    output(json, { ok: true, added, total: existing.size }, added.length > 0 ? `Added ${added.length} repo(s)` : "No changes");
+}
+async function reposRemove(path, options) {
+    const json = Boolean(options.json);
+    const absolutePath = toAbsolutePath(path);
+    const config = loadConfig();
+    const before = config.repos.length;
+    config.repos = config.repos.filter((repoPath) => repoPath !== absolutePath);
+    if (config.repos.length !== before) {
+        saveConfig(config);
+    }
+    output(json, {
+        ok: true,
+        removed: before !== config.repos.length ? absolutePath : null,
+        total: config.repos.length,
+    }, before !== config.repos.length ? "Repo removed" : "No changes");
+}
+async function reposList(options) {
+    const json = Boolean(options.json);
+    const config = loadConfig();
+    output(json, { ok: true, repos: config.repos }, config.repos.length > 0 ? config.repos.join(", ") : "No repos configured");
+}
+async function reposScan(directory, options) {
+    const json = Boolean(options.json);
+    const absoluteDirectory = toAbsolutePath(directory);
+    if (!existsSync(absoluteDirectory) || !statSync(absoluteDirectory).isDirectory()) {
+        fail(json, `Directory not found: ${absoluteDirectory}`);
+        return;
+    }
+    const found = collectGitRepos(absoluteDirectory);
+    const config = loadConfig();
+    const existing = new Set(config.repos);
+    const added = [];
+    for (const repoPath of found) {
+        if (!existing.has(repoPath)) {
+            existing.add(repoPath);
+            added.push(repoPath);
+        }
+    }
+    if (added.length > 0) {
+        config.repos = [...existing];
+        saveConfig(config);
     }
+    output(json, { ok: true, scanned: absoluteDirectory, found, added, total: existing.size }, added.length > 0 ? `Added ${added.length} repo(s)` : "No changes");
+}
+async function calendarSet(enabled, options) {
+    const json = Boolean(options.json);
+    const config = loadConfig();
+    const changed = config.calendar.enabled !== enabled;
+    config.calendar.enabled = enabled;
+    if (changed) {
+        saveConfig(config);
+    }
+    output(json, { ok: true, enabled }, changed ? `Calendar ${enabled ? "enabled" : "disabled"}` : "No changes");
+}
+async function calendarTest(options) {
+    const json = Boolean(options.json);
+    const result = runCommand("gws --help");
+    if (!result.ok) {
+        fail(json, "Calendar test failed");
+        return;
+    }
+    output(json, { ok: true, backend: "gws" }, "Calendar test passed");
+}
+async function githubTest(options) {
+    const json = Boolean(options.json);
+    const result = runCommand("gh auth status");
+    if (!result.ok) {
+        fail(json, "GitHub test failed");
+        return;
+    }
+    output(json, { ok: true }, "GitHub auth is valid");
+}
+async function projectsAdd(name, options) {
+    const json = Boolean(options.json);
+    if (!options.dir) {
+        fail(json, "--dir is required");
+        return;
+    }
+    const absoluteDirectory = toAbsolutePath(options.dir);
+    if (!existsSync(absoluteDirectory) || !statSync(absoluteDirectory).isDirectory()) {
+        fail(json, `Directory not found: ${absoluteDirectory}`);
+        return;
+    }
+    const config = loadConfig();
+    const existing = config.projects[name];
+    const changed = !existing || existing.path !== absoluteDirectory;
+    config.projects[name] = { path: absoluteDirectory };
+    if (changed) {
+        saveConfig(config);
+    }
+    output(json, { ok: true, name, path: absoluteDirectory }, changed ? "Project saved" : "No changes");
+}
+async function projectsRemove(name, options) {
+    const json = Boolean(options.json);
+    const config = loadConfig();
+    if (config.projects[name]) {
+        delete config.projects[name];
+        saveConfig(config);
+        output(json, { ok: true, removed: name }, "Project removed");
+        return;
+    }
+    output(json, { ok: true, removed: null }, "No changes");
+}
+async function projectsList(options) {
+    const json = Boolean(options.json);
+    const config = loadConfig();
+    const projects = Object.entries(config.projects).map(([name, project]) => ({
+        name,
+        path: project.path,
+    }));
+    output(json, { ok: true, projects }, projects.length > 0
+        ? projects.map((project) => `${project.name}=${project.path}`).join(", ")
+        : "No projects configured");
+}
+export function registerConfigCommand(program) {
+    const config = program
+        .command("config")
+        .description("View or edit configuration")
+        .argument("[key]")
+        .argument("[value]")
+        .option("--json", "Output as JSON")
+        .action(configCommand);
+    const repos = config.command("repos").description("Manage watched repos");
+    repos
+        .command("add <path...>")
+        .description("Add one or more repo paths")
+        .option("--json", "Output as JSON")
+        .action(reposAdd);
+    repos
+        .command("remove <path>")
+        .description("Remove a repo path")
+        .option("--json", "Output as JSON")
+        .action(reposRemove);
+    repos
+        .command("list")
+        .description("List watched repos")
+        .option("--json", "Output as JSON")
+        .action(reposList);
+    repos
+        .command("scan <directory>")
+        .description("Recursively scan for .git directories")
+        .option("--json", "Output as JSON")
+        .action(reposScan);
+    const calendar = config.command("calendar").description("Manage calendar integration");
+    calendar
+        .command("enable")
+        .description("Enable calendar integration")
+        .option("--json", "Output as JSON")
+        .action(async (options) => calendarSet(true, options));
+    calendar
+        .command("disable")
+        .description("Disable calendar integration")
+        .option("--json", "Output as JSON")
+        .action(async (options) => calendarSet(false, options));
+    calendar
+        .command("test")
+        .description("Test gws availability")
+        .option("--json", "Output as JSON")
+        .action(calendarTest);
+    const github = config.command("github").description("Manage GitHub integration");
+    github
+        .command("test")
+        .description("Test gh auth status")
+        .option("--json", "Output as JSON")
+        .action(githubTest);
+    const projects = config.command("projects").description("Manage projects");
+    projects
+        .command("add <name>")
+        .description("Add or update a project")
+        .requiredOption("--dir <path>", "Project directory")
+        .option("--json", "Output as JSON")
+        .action(projectsAdd);
+    projects
+        .command("remove <name>")
+        .description("Remove a project")
+        .option("--json", "Output as JSON")
+        .action(projectsRemove);
+    projects
+        .command("list")
+        .description("List projects")
+        .option("--json", "Output as JSON")
+        .action(projectsList);
 }
 //# sourceMappingURL=config.js.map