os-context 0.1.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright (c) 2025 Treadie, Inc
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# OS Context
+
+A fast macOS & Linux CLI that prints a single JSON object describing your current local context for agents. Privacy-respecting, read-only, no network calls to external services.
+
+OS Context gives AI agents a quick, local snapshot of your machine (app, window, clipboard, battery, network, etc.) so they can give context-aware answers without screenshots or daemons. Sensitive data is opt-in; default output is minimal and private.
+
+## Goals
+
+- **Single command**: `context` outputs JSON to stdout.
+- **Fast**: Target <300ms typical; local-only, no external network.
+- **Read-only**: No daemon, no always-on logging.
+- **Privacy**: No screenshots, keystrokes, microphone/camera, or recording.
+- **Clear permissions**: Only request macOS permissions when you use the matching flag (e.g. `--frontmost-window`, `--calendar`).
+- **Feature flags**: Sensitive data (clipboard, window title, calendar, reminders) is opt-in.
+
+## Install
+
+```bash
+npm install
+npm run build
+# Or link globally: npm link
+```
+
+## Usage
+
+**Default (safe core context only):**
+
+```bash
+context
+```
+
+**Pretty-print with frontmost window and clipboard, redact sensitive fields:**
+
+```bash
+context --pretty --frontmost-window --clipboard --redact
+```
+
+**All optional features and debug timings:**
+
+```bash
+context --pretty --clipboard --frontmost-window --apps \
+  --battery --network --calendar --reminders \
+  --redact --debug
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--pretty` | Pretty-print JSON. |
+| `--clipboard` | Include clipboard text (and types). |
+| `--frontmost-window` | Include frontmost window title (requires Accessibility). |
+| `--apps` | Include list of running apps (name, bundle_id, pid). |
+| `--battery` | Include battery percentage and charging state. |
+| `--network` | Include primary interface, SSID, local reachability. |
+| `--calendar` | Include next calendar events (requires Calendar permission). |
+| `--reminders` | Include reminders (requires Reminders permission). |
+| `--redact` | Redact sensitive strings; output SHA-256 + length only. |
+| `--timeout-ms <n>` | Per-module timeout in ms (default 250). |
+| `--debug` | Include per-module timings in `_debug.timings_ms`. |
+
+## Exit codes
+
+- **0** — Success.
+- **2** — Required permission missing (e.g. Accessibility or Calendar denied).
+- **3** — Timeout.
+- **4** — Other error.
+
+JSON is always printed, even when exit code is non-zero.
+
+## Platform support
+
+- **macOS**: Full support. Calendar and Reminders are macOS-only (AppleScript).
+- **Linux**: Host, frontmost (X11 via `xdotool`), apps (`ps`), clipboard (`xclip` or `xsel`), battery (`/sys/class/power_supply`), network (`ip`, `iwgetid`). Window title on Linux requires X11; on Wayland `xdotool` may not work. Calendar/Reminders return empty on Linux.
+- **Optional Linux deps**: `xdotool` (frontmost/window), `xclip` or `xsel` (clipboard), `iwgetid` (WiFi SSID).
+
+## Permissions
+
+- **Default run** does not require Accessibility, Calendar, or Reminders. It only reads OS version, machine, locale, timezone, and frontmost app name/bundle ID.
+- **Accessibility** (macOS) is only needed for `--frontmost-window` (to read window titles).
+- **Calendar / Reminders** (macOS) are only used when you pass `--calendar` or `--reminders`.
+
+See [docs/permissions.md](docs/permissions.md) for details and troubleshooting.
+
+## Output schema
+
+See [docs/schema.md](docs/schema.md) for the full JSON schema. Top-level keys include `schema_version`, `generated_at`, `host`, `frontmost`, optional `apps`, `clipboard`, `battery`, `network`, `calendar`, `reminders`, `permissions`, `warnings`, `errors`, and optionally `_debug`.
+
+## Development
+
+```bash
+npm run dev -- --pretty
+npm run build
+npm test
+```
+
+## License
+
+[FSL-1.1-MIT](LICENSE)

package/dist/index.js

@@ -0,0 +1,811 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/schema.ts
+import { z } from "zod";
+var SCHEMA_VERSION = "0.1.0";
+var HostSchema = z.object({
+  os: z.enum(["macos", "linux"]),
+  os_version: z.string(),
+  machine: z.string(),
+  locale: z.string(),
+  timezone: z.string()
+});
+var FrontmostSchema = z.object({
+  app_name: z.string(),
+  bundle_id: z.string(),
+  window_title: z.string().optional(),
+  window_title_sha256: z.string().optional(),
+  window_title_length: z.number().optional()
+});
+var AppEntrySchema = z.object({
+  name: z.string(),
+  bundle_id: z.string(),
+  pid: z.number()
+});
+var ClipboardSchema = z.object({
+  available: z.boolean(),
+  types: z.array(z.string()),
+  text: z.string().optional(),
+  text_sha256: z.string().optional(),
+  text_length: z.number().optional()
+});
+var BatterySchema = z.object({
+  percentage: z.number(),
+  is_charging: z.boolean(),
+  power_source: z.enum(["ac", "battery", "unknown"])
+});
+var NetworkSchema = z.object({
+  primary_interface: z.string(),
+  ssid: z.string().optional(),
+  has_internet: z.boolean()
+});
+var CalendarEventSchema = z.object({
+  start: z.string(),
+  end: z.string(),
+  title: z.string(),
+  location: z.string().optional()
+});
+var ReminderSchema = z.object({
+  title: z.string(),
+  due: z.string().optional(),
+  list: z.string().optional()
+});
+var PermissionStateSchema = z.enum([
+  "granted",
+  "denied",
+  "not_requested",
+  "unknown"
+]);
+var PermissionsSchema = z.object({
+  accessibility: PermissionStateSchema,
+  calendar: PermissionStateSchema,
+  reminders: PermissionStateSchema
+});
+var StructuredErrorSchema = z.object({
+  module: z.string(),
+  message: z.string(),
+  code: z.string().optional()
+});
+var DebugSchema = z.object({
+  timings_ms: z.record(z.string(), z.number())
+});
+var OutputSchema = z.object({
+  schema_version: z.string(),
+  generated_at: z.string(),
+  host: HostSchema.optional(),
+  frontmost: FrontmostSchema.optional(),
+  apps: z.array(AppEntrySchema).optional(),
+  clipboard: ClipboardSchema.optional(),
+  battery: BatterySchema.optional(),
+  network: NetworkSchema.optional(),
+  calendar: z.array(CalendarEventSchema).optional(),
+  reminders: z.array(ReminderSchema).optional(),
+  permissions: PermissionsSchema,
+  warnings: z.array(z.string()).optional(),
+  errors: z.array(StructuredErrorSchema).optional(),
+  _debug: DebugSchema.optional()
+});
+
+// src/modules/permissions.ts
+var DEFAULT = "not_requested";
+function createPermissionsState() {
+  return {
+    accessibility: DEFAULT,
+    calendar: DEFAULT,
+    reminders: DEFAULT
+  };
+}
+function updatePermission(state, key, value) {
+  state[key] = value;
+}
+
+// src/util/exec.ts
+import { execa } from "execa";
+async function run(cmd, args, options) {
+  try {
+    const result = await execa(cmd, args, {
+      timeout: options.timeoutMs,
+      reject: false,
+      all: false
+    });
+    return {
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      ok: result.exitCode === 0,
+      timedOut: result.timedOut
+    };
+  } catch (err) {
+    const e = err;
+    return {
+      stdout: e.stdout ?? "",
+      stderr: e.stderr ?? "",
+      ok: false,
+      timedOut: e.timedOut ?? false
+    };
+  }
+}
+
+// src/util/time.ts
+function elapsedMs(start) {
+  return Math.round(performance.now() - start);
+}
+function timer() {
+  const start = performance.now();
+  return {
+    elapsed: () => elapsedMs(start)
+  };
+}
+
+// src/util/platform.ts
+function getPlatform() {
+  const p = process.platform;
+  if (p === "darwin") return "darwin";
+  if (p === "linux") return "linux";
+  return "unsupported";
+}
+
+// src/modules/host.ts
+async function collectHostDarwin(timeoutMs) {
+  const t = timer();
+  const warnings = [];
+  try {
+    const [osVersion, machine] = await Promise.all([
+      run("sw_vers", ["-productVersion"], { timeoutMs }),
+      run("uname", ["-m"], { timeoutMs })
+    ]);
+    if (osVersion.timedOut || machine.timedOut) {
+      return {
+        warnings: [...warnings, "host: timeout"],
+        error: { module: "host", message: "Timeout", code: "timeout" },
+        timingMs: t.elapsed()
+      };
+    }
+    const os_version = osVersion.ok ? osVersion.stdout.trim() || "unknown" : "unknown";
+    const machine_arch = machine.ok ? machine.stdout.trim() || "unknown" : "unknown";
+    const locale = typeof Intl !== "undefined" && Intl.DateTimeFormat ? new Intl.DateTimeFormat().resolvedOptions().locale : "en-US";
+    const tz = typeof Intl !== "undefined" && Intl.DateTimeFormat ? new Intl.DateTimeFormat().resolvedOptions().timeZone : "UTC";
+    const data = {
+      os: "macos",
+      os_version,
+      machine: machine_arch,
+      locale,
+      timezone: tz
+    };
+    return { data, warnings: warnings.length ? warnings : void 0, timingMs: t.elapsed() };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      warnings,
+      error: { module: "host", message, code: "error" },
+      timingMs: t.elapsed()
+    };
+  }
+}
+function parseOsRelease(stdout) {
+  const version = stdout.match(/^VERSION_ID="?([^"\n]+)"?/m)?.[1] ?? stdout.match(/^PRETTY_NAME="?([^"\n]+)"?/m)?.[1] ?? "unknown";
+  return { version };
+}
+async function collectHostLinux(timeoutMs) {
+  const t = timer();
+  const warnings = [];
+  try {
+    const [osRelease, machine] = await Promise.all([
+      run("cat", ["/etc/os-release"], { timeoutMs }),
+      run("uname", ["-m"], { timeoutMs })
+    ]);
+    if (osRelease.timedOut || machine.timedOut) {
+      return {
+        warnings: [...warnings, "host: timeout"],
+        error: { module: "host", message: "Timeout", code: "timeout" },
+        timingMs: t.elapsed()
+      };
+    }
+    const { version } = osRelease.ok ? parseOsRelease(osRelease.stdout) : { version: "unknown" };
+    const machine_arch = machine.ok ? machine.stdout.trim() || "unknown" : "unknown";
+    const locale = typeof Intl !== "undefined" && Intl.DateTimeFormat ? new Intl.DateTimeFormat().resolvedOptions().locale : "en-US";
+    const tz = typeof Intl !== "undefined" && Intl.DateTimeFormat ? new Intl.DateTimeFormat().resolvedOptions().timeZone : "UTC";
+    const data = {
+      os: "linux",
+      os_version: version,
+      machine: machine_arch,
+      locale,
+      timezone: tz
+    };
+    return { data, warnings: warnings.length ? warnings : void 0, timingMs: t.elapsed() };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      warnings,
+      error: { module: "host", message, code: "error" },
+      timingMs: t.elapsed()
+    };
+  }
+}
+async function collectHost(timeoutMs) {
+  const platform = getPlatform();
+  if (platform === "darwin") return collectHostDarwin(timeoutMs);
+  if (platform === "linux") return collectHostLinux(timeoutMs);
+  return {
+    error: { module: "host", message: `Unsupported platform: ${process.platform}`, code: "unsupported" },
+    timingMs: 0
+  };
+}
+
+// src/util/redact.ts
+import { createHash } from "crypto";
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function redactString(value) {
+  return {
+    sha256: sha256(value),
+    length: value.length
+  };
+}
+
+// src/modules/frontmost.ts
+var ACCESSIBILITY_DENIED_PATTERNS = [
+  /not authorised to send apple events/i,
+  /accessibility/i,
+  /not allowed to send/i
+];
+function isAccessibilityDenied(stderr) {
+  return ACCESSIBILITY_DENIED_PATTERNS.some((p) => p.test(stderr));
+}
+async function collectFrontmostDarwin(options) {
+  const t = timer();
+  const timeoutMs = options.timeoutMs;
+  const includeWindow = options.includeFrontmostWindow;
+  const redact = options.redact;
+  const warnings = [];
+  try {
+    const nameResult = await run("osascript", [
+      "-e",
+      'tell application "System Events" to get name of first application process whose frontmost is true'
+    ], { timeoutMs });
+    if (nameResult.timedOut) {
+      return {
+        warnings: [...warnings, "frontmost: timeout"],
+        error: { module: "frontmost", message: "Timeout", code: "timeout" },
+        timingMs: t.elapsed()
+      };
+    }
+    if (!nameResult.ok) {
+      if (isAccessibilityDenied(nameResult.stderr)) {
+        return {
+          permission: "denied",
+          error: {
+            module: "frontmost",
+            message: "Accessibility permission required for frontmost app",
+            code: "permission_denied"
+          },
+          timingMs: t.elapsed()
+        };
+      }
+      return {
+        error: {
+          module: "frontmost",
+          message: nameResult.stderr.trim() || "Failed to get frontmost app",
+          code: "error"
+        },
+        timingMs: t.elapsed()
+      };
+    }
+    const appName = nameResult.stdout.trim() || "Unknown";
+    if (!appName) {
+      return {
+        data: { app_name: "Unknown", bundle_id: "unknown" },
+        timingMs: t.elapsed()
+      };
+    }
+    const idResult = await run("osascript", [
+      "-e",
+      `id of application "${appName.replace(/"/g, '\\"')}"`
+    ], { timeoutMs });
+    const bundle_id = idResult.ok ? idResult.stdout.trim() || "unknown" : "unknown";
+    const frontmost = { app_name: appName, bundle_id };
+    if (includeWindow) {
+      const windowResult = await run("osascript", [
+        "-e",
+        'tell application "System Events" to tell (first application process whose frontmost is true) to get name of front window'
+      ], { timeoutMs });
+      if (windowResult.timedOut) {
+        warnings.push("frontmost window: timeout");
+      } else if (!windowResult.ok) {
+        if (isAccessibilityDenied(windowResult.stderr)) {
+          return {
+            data: frontmost,
+            permission: "denied",
+            error: {
+              module: "frontmost",
+              message: "Accessibility permission required for window title",
+              code: "permission_denied"
+            },
+            warnings: warnings.length ? warnings : void 0,
+            timingMs: t.elapsed()
+          };
+        }
+        warnings.push("frontmost window: " + (windowResult.stderr.trim() || "unknown"));
+      } else {
+        const rawTitle = windowResult.stdout.trim() ?? "";
+        if (redact) {
+          const r = redactString(rawTitle);
+          frontmost.window_title_sha256 = r.sha256;
+          frontmost.window_title_length = r.length;
+        } else {
+          frontmost.window_title = rawTitle;
+          frontmost.window_title_length = rawTitle.length;
+        }
+      }
+    }
+    return {
+      data: frontmost,
+      warnings: warnings.length ? warnings : void 0,
+      timingMs: t.elapsed()
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      warnings,
+      error: { module: "frontmost", message, code: "error" },
+      timingMs: t.elapsed()
+    };
+  }
+}
+async function collectFrontmostLinux(options) {
+  const t = timer();
+  const timeoutMs = options.timeoutMs;
+  const includeWindow = options.includeFrontmostWindow;
+  const redact = options.redact;
+  const warnings = [];
+  try {
+    const pidResult = await run("xdotool", ["getactivewindow", "getwindowpid"], { timeoutMs });
+    const titleResult = includeWindow ? await run("xdotool", ["getactivewindow", "getwindowname"], { timeoutMs }) : { ok: false, stdout: "", stderr: "", timedOut: false };
+    if (pidResult.timedOut) {
+      return {
+        warnings: [...warnings, "frontmost: timeout"],
+        error: { module: "frontmost", message: "Timeout", code: "timeout" },
+        timingMs: t.elapsed()
+      };
+    }
+    let appName = "Unknown";
+    let bundle_id = "unknown";
+    if (pidResult.ok && pidResult.stdout.trim()) {
+      const pid = pidResult.stdout.trim();
+      const commResult = await run("cat", [`/proc/${pid}/comm`], { timeoutMs });
+      if (commResult.ok && commResult.stdout.trim()) {
+        appName = commResult.stdout.trim().replace(/\n$/, "");
+        bundle_id = appName;
+      }
+    }
+    const frontmost = { app_name: appName, bundle_id };
+    if (includeWindow && titleResult.ok) {
+      const rawTitle = titleResult.stdout.trim() ?? "";
+      if (redact) {
+        const r = redactString(rawTitle);
+        frontmost.window_title_sha256 = r.sha256;
+        frontmost.window_title_length = r.length;
+      } else {
+        frontmost.window_title = rawTitle;
+        frontmost.window_title_length = rawTitle.length;
+      }
+    } else if (includeWindow && !pidResult.ok) {
+      warnings.push("frontmost: xdotool not available or no X11 (e.g. Wayland); install xdotool for X11");
+    }
+    return {
+      data: frontmost,
+      warnings: warnings.length ? warnings : void 0,
+      timingMs: t.elapsed()
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      warnings,
+      error: { module: "frontmost", message, code: "error" },
+      timingMs: t.elapsed()
+    };
+  }
+}
+async function collectFrontmost(options) {
+  const platform = getPlatform();
+  if (platform === "darwin") return collectFrontmostDarwin(options);
+  if (platform === "linux") return collectFrontmostLinux(options);
+  return {
+    data: { app_name: "Unknown", bundle_id: "unknown" },
+    error: { module: "frontmost", message: `Unsupported platform: ${process.platform}`, code: "unsupported" },
+    timingMs: 0
+  };
+}
+
+// src/modules/apps.ts
+var MAX_APPS = 50;
+async function collectAppsDarwin(_timeoutMs) {
+  return { data: [], timingMs: 0 };
+}
+async function collectAppsLinux(timeoutMs) {
+  const t = timer();
+  try {
+    const result = await run("ps", ["-e", "-o", "pid=", "-o", "comm="], { timeoutMs });
+    if (result.timedOut || !result.ok) {
+      return {
+        data: [],
+        error: result.timedOut ? { module: "apps", message: "Timeout", code: "timeout" } : { module: "apps", message: result.stderr.trim() || "Failed to list processes", code: "error" },
+        timingMs: t.elapsed()
+      };
+    }
+    const lines = result.stdout.trim().split("\n").filter(Boolean).slice(0, MAX_APPS);
+    const apps = lines.map((line) => {
+      const match = line.trim().match(/^\s*(\d+)\s+(.+)$/);
+      const pid = match ? parseInt(match[1], 10) : 0;
+      const name = match ? match[2].trim() || "unknown" : "unknown";
+      return { name, bundle_id: name, pid: Number.isNaN(pid) ? 0 : pid };
+    }).filter((a) => a.pid > 0);
+    return { data: apps, timingMs: t.elapsed() };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      data: [],
+      error: { module: "apps", message, code: "error" },
+      timingMs: t.elapsed()
+    };
+  }
+}
+async function collectApps(timeoutMs) {
+  const platform = getPlatform();
+  if (platform === "darwin") return collectAppsDarwin(timeoutMs);
+  if (platform === "linux") return collectAppsLinux(timeoutMs);
+  return { data: [], timingMs: 0 };
+}
+
+// src/modules/clipboard.ts
+async function collectClipboardDarwin(_options) {
+  return {
+    data: { available: false, types: [] },
+    timingMs: 0
+  };
+}
+async function collectClipboardLinux(options) {
+  const t = timer();
+  const timeoutMs = options.timeoutMs;
+  const redact = options.redact;
+  try {
+    let result = await run("xclip", ["-selection", "clipboard", "-o"], { timeoutMs });
+    if (!result.ok) {
+      result = await run("xsel", ["--clipboard", "--output"], { timeoutMs });
+    }
+    if (!result.ok) {
+      return {
+        data: { available: false, types: [] },
+        timingMs: t.elapsed()
+      };
+    }
+    const text = result.stdout ?? "";
+    const types = text.length > 0 ? ["text/plain"] : [];
+    const data = {
+      available: true,
+      types
+    };
+    if (text.length > 0) {
+      if (redact) {
+        const r = redactString(text);
+        data.text_sha256 = r.sha256;
+        data.text_length = r.length;
+      } else {
+        data.text = text;
+        data.text_length = text.length;
+      }
+    }
+    return { data, timingMs: t.elapsed() };
+  } catch {
+    return {
+      data: { available: false, types: [] },
+      timingMs: t.elapsed()
+    };
+  }
+}
+async function collectClipboard(options) {
+  const platform = getPlatform();
+  if (platform === "darwin") return collectClipboardDarwin(options);
+  if (platform === "linux") return collectClipboardLinux(options);
+  return {
+    data: { available: false, types: [] },
+    timingMs: 0
+  };
+}
+
+// src/modules/battery.ts
+import { readFile } from "fs/promises";
+async function collectBatteryDarwin(_timeoutMs) {
+  return {
+    data: { percentage: 0, is_charging: false, power_source: "unknown" },
+    timingMs: 0
+  };
+}
+async function collectBatteryLinux(_timeoutMs) {
+  const t = timer();
+  try {
+    const base = "/sys/class/power_supply";
+    const batDir = "BAT0";
+    const capacityPath = `${base}/${batDir}/capacity`;
+    const statusPath = `${base}/${batDir}/status`;
+    const capacity = await readFile(capacityPath, "utf8").then((s) => parseInt(s.trim(), 10)).catch(() => NaN);
+    const status = await readFile(statusPath, "utf8").then((s) => s.trim().toLowerCase()).catch(() => "");
+    const percentage = Number.isNaN(capacity) ? 0 : Math.min(1, Math.max(0, capacity / 100));
+    const is_charging = status === "charging" || status === "full";
+    const power_source = status === "charging" || status === "full" ? "ac" : status === "discharging" ? "battery" : "unknown";
+    const data = { percentage, is_charging, power_source };
+    return { data, timingMs: t.elapsed() };
+  } catch {
+    return {
+      data: { percentage: 0, is_charging: false, power_source: "unknown" },
+      timingMs: t.elapsed()
+    };
+  }
+}
+async function collectBattery(timeoutMs) {
+  const platform = getPlatform();
+  if (platform === "darwin") return collectBatteryDarwin(timeoutMs);
+  if (platform === "linux") return collectBatteryLinux(timeoutMs);
+  return {
+    data: { percentage: 0, is_charging: false, power_source: "unknown" },
+    timingMs: 0
+  };
+}
+
+// src/modules/network.ts
+import { readFile as readFile2 } from "fs/promises";
+async function collectNetworkDarwin(_timeoutMs) {
+  return {
+    data: { primary_interface: "", has_internet: false },
+    timingMs: 0
+  };
+}
+async function collectNetworkLinux(timeoutMs) {
+  const t = timer();
+  try {
+    const routeResult = await run("ip", ["route", "show", "default"], { timeoutMs });
+    const defaultLine = routeResult.ok ? routeResult.stdout.trim().split("\n")[0] : "";
+    const match = defaultLine.match(/dev\s+(\S+)/);
+    const primary_interface = match ? match[1] : "";
+    let ssid;
+    if (primary_interface) {
+      const iwResult = await run("iwgetid", ["-r", primary_interface], { timeoutMs });
+      if (iwResult.ok && iwResult.stdout.trim()) ssid = iwResult.stdout.trim();
+    }
+    let has_internet = false;
+    if (primary_interface) {
+      try {
+        const operstate = await readFile2(
+          `/sys/class/net/${primary_interface}/operstate`,
+          "utf8"
+        ).then((s) => s.trim()).catch(() => "");
+        const hasCarrier = operstate === "up";
+        if (hasCarrier) {
+          const addrResult = await run("ip", ["-4", "addr", "show", primary_interface], { timeoutMs });
+          has_internet = addrResult.ok && /inet\s+\d+\.\d+\.\d+\.\d+/.test(addrResult.stdout);
+        }
+      } catch {
+      }
+    }
+    const data = { primary_interface, ssid, has_internet };
+    return { data, timingMs: t.elapsed() };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      data: { primary_interface: "", has_internet: false },
+      error: { module: "network", message, code: "error" },
+      timingMs: t.elapsed()
+    };
+  }
+}
+async function collectNetwork(timeoutMs) {
+  const platform = getPlatform();
+  if (platform === "darwin") return collectNetworkDarwin(timeoutMs);
+  if (platform === "linux") return collectNetworkLinux(timeoutMs);
+  return {
+    data: { primary_interface: "", has_internet: false },
+    timingMs: 0
+  };
+}
+
+// src/modules/calendar.ts
+async function collectCalendar(_options) {
+  if (getPlatform() === "linux") {
+    return { data: [], timingMs: 0 };
+  }
+  return { data: [], timingMs: 0 };
+}
+
+// src/modules/reminders.ts
+async function collectReminders(_options) {
+  if (getPlatform() === "linux") {
+    return { data: [], timingMs: 0 };
+  }
+  return { data: [], timingMs: 0 };
+}
+
+// src/util/json.ts
+function stableStringify(obj, pretty = false) {
+  return JSON.stringify(obj, stableReplacer, pretty ? 2 : 0);
+}
+function stableReplacer(_key, value) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return Object.keys(value).sort().reduce((acc, k) => {
+      acc[k] = value[k];
+      return acc;
+    }, {});
+  }
+  return value;
+}
+
+// src/index.ts
+var DEFAULT_TIMEOUT_MS = 250;
+function parseArgs() {
+  const program = new Command();
+  program.name("context").description(
+    "Print a single JSON object describing your current local context (for agents). Supports macOS and Linux. Privacy-respecting, read-only, no network calls to external services. Sensitive data (clipboard, window title, calendar, reminders) is opt-in via flags."
+  ).option("--pretty", "Pretty-print JSON").option("--clipboard", "Include clipboard text (may prompt for pasteboard access)").option(
+    "--frontmost-window",
+    "Include frontmost window title (requires Accessibility permission)"
+  ).option("--apps", "Include list of running apps (name, bundle_id, pid)").option("--battery", "Include battery percentage and charging state").option("--network", "Include primary interface, SSID, local reachability").option("--calendar", "Include next calendar events (requires Calendar permission)").option("--reminders", "Include reminders (requires Reminders permission)").option(
+    "--redact",
+    "Redact sensitive string fields (clipboard, window title, event/reminder titles); output sha256 + length"
+  ).option("--timeout-ms <n>", "Per-module timeout in ms", (v) => parseInt(v, 10), DEFAULT_TIMEOUT_MS).option("--debug", "Include per-module timings in JSON under _debug").addHelpText(
+    "after",
+    `
+Privacy & permissions:
+  By default, context only reads safe system info (OS, machine, locale, frontmost app name).
+  It does NOT read clipboard, window titles, calendar, or reminders unless you pass the
+  corresponding flag (--clipboard, --frontmost-window, etc.). Accessibility is only required for --frontmost-window.
+  Calendar/Reminders permissions are only requested when --calendar or --reminders
+  is used. No screenshots, keystrokes, or recording of any kind.
+`
+  );
+  program.parse();
+  const opts = program.opts();
+  return {
+    pretty: opts.pretty ?? false,
+    includeClipboard: opts.clipboard ?? false,
+    includeFrontmostWindow: opts.frontmostWindow ?? false,
+    includeApps: opts.apps ?? false,
+    includeBattery: opts.battery ?? false,
+    includeNetwork: opts.network ?? false,
+    includeCalendar: opts.calendar ?? false,
+    includeReminders: opts.reminders ?? false,
+    redact: opts.redact ?? false,
+    timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    debug: opts.debug ?? false
+  };
+}
+async function collectAll(options) {
+  const permissions = createPermissionsState();
+  const warnings = [];
+  const errors = [];
+  const timingsMs = {};
+  let exitCode = 0;
+  function addError(module, message, code) {
+    errors.push({ module, message, code });
+  }
+  function setExit(code) {
+    if (code === 2) exitCode = 2;
+    else if (code === 3 && exitCode !== 2) exitCode = 3;
+    else if (code === 4 && exitCode !== 2 && exitCode !== 3) exitCode = 4;
+  }
+  function recordTiming(name, ms) {
+    timingsMs[name] = ms;
+  }
+  const hostResult = await collectHost(options.timeoutMs);
+  if (hostResult.timingMs != null) recordTiming("host", hostResult.timingMs);
+  if (hostResult.error) {
+    addError("host", hostResult.error.message, hostResult.error.code);
+    if (hostResult.error.code === "timeout") setExit(3);
+    else setExit(4);
+  }
+  if (hostResult.warnings) warnings.push(...hostResult.warnings);
+  const frontmostResult = await collectFrontmost(options);
+  if (frontmostResult.timingMs != null) recordTiming("frontmost", frontmostResult.timingMs);
+  if (frontmostResult.permission) updatePermission(permissions, "accessibility", frontmostResult.permission);
+  if (frontmostResult.error) {
+    addError("frontmost", frontmostResult.error.message, frontmostResult.error.code);
+    if (frontmostResult.permission === "denied") setExit(2);
+    else if (frontmostResult.error.code === "timeout") setExit(3);
+    else setExit(4);
+  }
+  if (frontmostResult.warnings) warnings.push(...frontmostResult.warnings);
+  let appsResult = {};
+  if (options.includeApps) {
+    appsResult = await collectApps(options.timeoutMs);
+    if (appsResult.timingMs != null) recordTiming("apps", appsResult.timingMs);
+    if (appsResult.error) {
+      addError("apps", appsResult.error.message, appsResult.error.code);
+      if (appsResult.error.code === "timeout") setExit(3);
+    }
+    if (appsResult.warnings) warnings.push(...appsResult.warnings);
+  }
+  let clipboardResult = {};
+  if (options.includeClipboard) {
+    clipboardResult = await collectClipboard(options);
+    if (clipboardResult.timingMs != null) recordTiming("clipboard", clipboardResult.timingMs);
+    if (clipboardResult.error) {
+      addError("clipboard", clipboardResult.error.message, clipboardResult.error.code);
+      if (clipboardResult.error.code === "timeout") setExit(3);
+    }
+    if (clipboardResult.warnings) warnings.push(...clipboardResult.warnings);
+  }
+  let batteryResult = {};
+  if (options.includeBattery) {
+    batteryResult = await collectBattery(options.timeoutMs);
+    if (batteryResult.timingMs != null) recordTiming("battery", batteryResult.timingMs);
+    if (batteryResult.error) {
+      addError("battery", batteryResult.error.message, batteryResult.error.code);
+      if (batteryResult.error.code === "timeout") setExit(3);
+    }
+    if (batteryResult.warnings) warnings.push(...batteryResult.warnings);
+  }
+  let networkResult = {};
+  if (options.includeNetwork) {
+    networkResult = await collectNetwork(options.timeoutMs);
+    if (networkResult.timingMs != null) recordTiming("network", networkResult.timingMs);
+    if (networkResult.error) {
+      addError("network", networkResult.error.message, networkResult.error.code);
+      if (networkResult.error.code === "timeout") setExit(3);
+    }
+    if (networkResult.warnings) warnings.push(...networkResult.warnings);
+  }
+  let calendarResult = {};
+  if (options.includeCalendar) {
+    calendarResult = await collectCalendar(options);
+    if (calendarResult.timingMs != null) recordTiming("calendar", calendarResult.timingMs);
+    if (calendarResult.permission) updatePermission(permissions, "calendar", calendarResult.permission);
+    if (calendarResult.error) {
+      addError("calendar", calendarResult.error.message, calendarResult.error.code);
+      if (calendarResult.permission === "denied") setExit(2);
+      else if (calendarResult.error.code === "timeout") setExit(3);
+      else setExit(4);
+    }
+    if (calendarResult.warnings) warnings.push(...calendarResult.warnings);
+  }
+  let remindersResult = {};
+  if (options.includeReminders) {
+    remindersResult = await collectReminders(options);
+    if (remindersResult.timingMs != null) recordTiming("reminders", remindersResult.timingMs);
+    if (remindersResult.permission) updatePermission(permissions, "reminders", remindersResult.permission);
+    if (remindersResult.error) {
+      addError("reminders", remindersResult.error.message, remindersResult.error.code);
+      if (remindersResult.permission === "denied") setExit(2);
+      else if (remindersResult.error.code === "timeout") setExit(3);
+      else setExit(4);
+    }
+    if (remindersResult.warnings) warnings.push(...remindersResult.warnings);
+  }
+  const output = {
+    schema_version: SCHEMA_VERSION,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    permissions,
+    warnings: warnings.length ? warnings : void 0,
+    errors: errors.length ? errors : void 0
+  };
+  if (hostResult.data != null) output.host = hostResult.data;
+  if (frontmostResult.data != null) output.frontmost = frontmostResult.data;
+  if (appsResult.data != null) output.apps = appsResult.data;
+  if (clipboardResult.data != null) output.clipboard = clipboardResult.data;
+  if (batteryResult.data != null) output.battery = batteryResult.data;
+  if (networkResult.data != null) output.network = networkResult.data;
+  if (calendarResult.data != null) output.calendar = calendarResult.data;
+  if (remindersResult.data != null) output.reminders = remindersResult.data;
+  if (options.debug) output._debug = { timings_ms: timingsMs };
+  return { output, exitCode };
+}
+async function main() {
+  const options = parseArgs();
+  const { output, exitCode } = await collectAll(options);
+  console.log(stableStringify(output, options.pretty));
+  process.exit(exitCode);
+}
+main();
+export {
+  collectAll
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "os-context",
+  "version": "0.1.0",
+  "description": "Fast macOS & Linux CLI that prints a single JSON object describing your current local context for agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "context": "dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": ["macos", "cli", "context", "agent"],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "execa": "^9.5.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.6"
+  }
+}