usight 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonatan
+
+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,42 @@
+# usight
+
+Install and manage [Übersicht](https://tracesof.net/uebersicht/) widgets directly from GitHub — no git required.
+
+## Installation
+
+```bash
+npm install -g usight
+```
+
+## Usage
+
+```bash
+# Install a widget from GitHub
+usight install hw2007/ubersicht-neofetch
+usight install https://github.com/hw2007/ubersicht-neofetch
+
+# Remove a widget
+usight uninstall ubersicht-neofetch
+
+# List installed widgets
+usight list
+
+# Change where widgets are cached
+usight set --path ~/my-widgets-cache
+
+# Show current config
+usight config
+```
+
+## How it works
+
+Downloads a GitHub repository as a tarball, extracts it into a local cache (`~/.cache/usight` by default), and creates a symlink in your Übersicht widgets directory. No git, no background processes, no telemetry.
+
+## Requirements
+
+- macOS
+- Node.js ≥ 18
+
+## License
+
+MIT

package/bin/usight.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import { install, uninstall, list, setPath } from '../lib/widgets.js';
+import { getConfig } from '../lib/config.js';
+import { getWidgetsDir } from '../lib/ubersicht.js';
+
+const [,, cmd, ...args] = process.argv;
+
+const commands = {
+  install: () => install(args[0]),
+  add:     () => install(args[0]),
+  uninstall: () => uninstall(args[0]),
+  remove:    () => uninstall(args[0]),
+  list: () => list(),
+  set: () => {
+    const i = args.indexOf('--path');
+    if (i === -1 || !args[i + 1]) {
+      console.error('Usage: usight set --path <path>');
+      process.exit(1);
+    }
+    setPath(args[i + 1]);
+  },
+  config: () => {
+    const cfg = getConfig();
+    console.log(`Cache path:   ${cfg.cachePath}`);
+    console.log(`Widgets dir:  ${getWidgetsDir()}`);
+    console.log(`Installed:    ${Object.keys(cfg.widgets).length} widget(s)`);
+  },
+  help: () => help(),
+};
+
+if (!cmd || !commands[cmd]) {
+  help();
+  process.exit(cmd ? 1 : 0);
+}
+
+Promise.resolve(commands[cmd]()).catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});
+
+function help() {
+  console.log(`
+usight — Übersicht widget manager
+
+  usight install <owner/repo>    Install a widget from GitHub
+  usight add <owner/repo>        Alias for install
+  usight uninstall <name>        Remove a widget
+  usight remove <name>           Alias for uninstall
+  usight list                    List installed widgets
+  usight set --path <path>       Change widget cache directory
+  usight config                  Show current configuration
+  usight help                    Show this help
+
+Examples:
+  usight install hw2007/ubersicht-neofetch
+  usight install https://github.com/hw2007/ubersicht-neofetch
+  usight uninstall ubersicht-neofetch
+`.trim());
+}

package/lib/config.js

@@ -0,0 +1,31 @@
+// Config lives at a fixed path so it survives cachePath changes.
+// Widget metadata is embedded in config — one file, no sync issues.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const CONFIG_DIR = join(homedir(), '.config', 'usight');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const DEFAULT_CACHE = join(homedir(), '.cache', 'usight');
+
+export function getConfig() {
+  if (!existsSync(CONFIG_FILE)) {
+    return { cachePath: DEFAULT_CACHE, widgets: {} };
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return { cachePath: DEFAULT_CACHE, widgets: {} };
+  }
+}
+
+export function saveConfig(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  mkdirSync(cfg.cachePath, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + '\n');
+}
+
+export function resolvePath(p) {
+  return p.startsWith('~') ? join(homedir(), p.slice(1)) : p;
+}

package/lib/github.js

@@ -0,0 +1,58 @@
+import https from 'https';
+import { mkdirSync } from 'fs';
+import { spawn } from 'child_process';
+
+// Parse "owner/repo" or full GitHub URL into { owner, repo }
+export function parseRepo(input) {
+  if (!input) throw new Error('No repository specified');
+
+  // strip trailing .git and leading https://github.com/
+  const clean = input
+    .replace(/^https?:\/\/github\.com\//, '')
+    .replace(/\.git$/, '')
+    .trim();
+
+  const parts = clean.split('/');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(`Invalid repo format: "${input}" — use owner/repo or https://github.com/owner/repo`);
+  }
+
+  return { owner: parts[0], repo: parts[1] };
+}
+
+// Download GitHub tarball and extract into destDir (streaming, no temp file).
+export function downloadAndExtract(owner, repo, destDir) {
+  mkdirSync(destDir, { recursive: true });
+
+  const url = `https://api.github.com/repos/${owner}/${repo}/tarball/HEAD`;
+
+  return new Promise((resolve, reject) => {
+    const get = (url) => {
+      https.get(url, { headers: { 'User-Agent': 'usight-cli' } }, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302 || res.statusCode === 307) {
+          get(res.headers.location);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`GitHub returned HTTP ${res.statusCode} for ${owner}/${repo}`));
+          return;
+        }
+
+        // pipe into tar — strips the top-level GitHub-generated directory
+        const tar = spawn('tar', ['-xzf', '-', '-C', destDir, '--strip-components=1'], {
+          stdio: ['pipe', 'inherit', 'inherit'],
+        });
+
+        res.pipe(tar.stdin);
+        res.on('error', reject);
+        tar.on('error', reject);
+        tar.on('close', (code) => {
+          if (code === 0) resolve();
+          else reject(new Error(`tar exited with code ${code}`));
+        });
+      }).on('error', reject);
+    };
+
+    get(url);
+  });
+}

package/lib/ubersicht.js

@@ -0,0 +1,25 @@
+import { execSync } from 'child_process';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const DEFAULT_WIDGETS_DIR = join(
+  homedir(),
+  'Library',
+  'Application Support',
+  'Übersicht',
+  'widgets'
+);
+
+// Try reading the actual configured path from Übersicht preferences.
+// Falls back to the default if Übersicht isn't installed or plist is unreadable.
+export function getWidgetsDir() {
+  try {
+    const plist = join(homedir(), 'Library/Preferences/com.felixhageloh.uebersicht.plist');
+    const json = execSync(`plutil -convert json -o - "${plist}"`, { stdio: ['pipe', 'pipe', 'pipe'] }).toString();
+    const prefs = JSON.parse(json);
+    if (prefs.widgetPath) return prefs.widgetPath;
+  } catch {
+    // Übersicht not installed or plist unreadable — use default
+  }
+  return DEFAULT_WIDGETS_DIR;
+}

package/lib/widgets.js

@@ -0,0 +1,133 @@
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, unlinkSync, renameSync } from 'fs';
+import { join } from 'path';
+import { getConfig, saveConfig, resolvePath } from './config.js';
+import { parseRepo, downloadAndExtract } from './github.js';
+import { getWidgetsDir } from './ubersicht.js';
+
+export async function install(repoArg) {
+  const { owner, repo } = parseRepo(repoArg);
+  const name = repo;
+
+  const cfg = getConfig();
+  if (cfg.widgets[name]) {
+    console.error(`"${name}" is already installed. Run: usight uninstall ${name}`);
+    process.exit(1);
+  }
+
+  const cacheDir = join(cfg.cachePath, name);
+  const widgetsDir = getWidgetsDir();
+  const symlinkPath = join(widgetsDir, name);
+
+  mkdirSync(widgetsDir, { recursive: true });
+
+  console.log(`Downloading ${owner}/${repo}...`);
+  await downloadAndExtract(owner, repo, cacheDir);
+
+  // Remove stale symlink if present
+  if (existsSync(symlinkPath) || isSymlink(symlinkPath)) {
+    unlinkSync(symlinkPath);
+  }
+  symlinkSync(cacheDir, symlinkPath);
+
+  cfg.widgets[name] = { repo: `${owner}/${repo}`, installedAt: new Date().toISOString() };
+  saveConfig(cfg);
+
+  console.log(`✓ Installed "${name}" → ${symlinkPath}`);
+}
+
+export function uninstall(name) {
+  if (!name) {
+    console.error('Usage: usight uninstall <name>');
+    process.exit(1);
+  }
+
+  const cfg = getConfig();
+  if (!cfg.widgets[name]) {
+    console.error(`"${name}" is not managed by usight`);
+    process.exit(1);
+  }
+
+  const cacheDir = join(cfg.cachePath, name);
+  const widgetsDir = getWidgetsDir();
+  const symlinkPath = join(widgetsDir, name);
+
+  if (existsSync(symlinkPath) || isSymlink(symlinkPath)) {
+    unlinkSync(symlinkPath);
+  }
+  if (existsSync(cacheDir)) {
+    rmSync(cacheDir, { recursive: true, force: true });
+  }
+
+  delete cfg.widgets[name];
+  saveConfig(cfg);
+
+  console.log(`✓ Removed "${name}"`);
+}
+
+export function list() {
+  const cfg = getConfig();
+  const entries = Object.entries(cfg.widgets);
+
+  if (entries.length === 0) {
+    console.log('No widgets installed. Try: usight install <owner/repo>');
+    return;
+  }
+
+  for (const [name, info] of entries) {
+    const date = info.installedAt ? new Date(info.installedAt).toLocaleDateString() : '?';
+    console.log(`  ${name}  (${info.repo})  installed ${date}`);
+  }
+}
+
+export function setPath(rawPath) {
+  if (!rawPath) {
+    console.error('Usage: usight set --path <path>');
+    process.exit(1);
+  }
+
+  const newPath = resolvePath(rawPath);
+  const cfg = getConfig();
+  const oldPath = cfg.cachePath;
+
+  if (newPath === oldPath) {
+    console.log(`Cache path is already ${oldPath}`);
+    return;
+  }
+
+  mkdirSync(newPath, { recursive: true });
+
+  const widgetsDir = getWidgetsDir();
+
+  // Move each managed widget dir and update its symlink
+  for (const name of Object.keys(cfg.widgets)) {
+    const src = join(oldPath, name);
+    const dst = join(newPath, name);
+    const symlinkPath = join(widgetsDir, name);
+
+    if (existsSync(src)) {
+      renameSync(src, dst);
+    }
+
+    // Re-point symlink to new location
+    if (existsSync(symlinkPath) || isSymlink(symlinkPath)) {
+      unlinkSync(symlinkPath);
+    }
+    if (existsSync(dst)) {
+      symlinkSync(dst, symlinkPath);
+    }
+  }
+
+  cfg.cachePath = newPath;
+  saveConfig(cfg);
+
+  console.log(`✓ Cache path set to ${newPath}`);
+}
+
+// lstatSync doesn't throw on broken symlinks, existsSync does — need both
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "usight",
+  "version": "0.1.4",
+  "description": "Manage installs for Übersicht widgets from GitHub — no git required",
+  "type": "module",
+  "bin": {
+    "usight": "bin/usight.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/test.js",
+    "release": "bash publish-npm.sh"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ubersicht",
+    "übersicht",
+    "widgets",
+    "macos",
+    "cli",
+    "widget-manager"
+  ],
+  "author": {
+    "name": "Jay F0x",
+    "email": "jjay56883@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayf0x/usight.git"
+  },
+  "homepage": "https://github.com/jayf0x/usight#readme",
+  "bugs": {
+    "url": "https://github.com/jayf0x/usight/issues"
+  }
+}