git0 0.3.66 → 0.3.68

package/docs/content/docs/meta.json

@@ -6,6 +6,7 @@
   "pages": [
     "---Getting Started---",
     "index",
+    "service",
     "---API Reference---",
     "modules",
     "git0",

package/docs/content/docs/service.mdx

@@ -0,0 +1,51 @@
+---
+title: Install Service
+description: Run git0 in the background so website download buttons install the right release and show progress in the button.
+---
+
+
+git0 can run as a small background service that turns any website's download button into a one-click installer. The button hands the service a repository; the service picks the release asset built for your OS and CPU, downloads it, installs it, and opens the app, while the button fills up as a progress bar.
+
+```bash
+git0 --service=install     # start at login and register git0:// links
+git0 --service=status      # is it running, and what is it installing
+git0 --service=uninstall   # remove it
+git0 --service            # or run it in the foreground, on 127.0.0.1:47100
+```
+
+It installs as a **per-user** service, because launching a desktop app has to happen inside your session: a `systemd --user` unit on Linux, a LaunchAgent on macOS, and a logon task on Windows. No admin rights are needed to install it.
+
+## Add the button to a site
+
+```html
+<a href="https://github.com/owner/repo/releases/latest" data-git0-repo="owner/repo">Download</a>
+<script src="https://unpkg.com/git0/demo/git0-button.js"></script>
+```
+
+When the service is running, clicking the link does not download a file. The button morphs into a progress bar showing the download, then the install, then the launch. When the service is not running, the link behaves as a normal link. `demo/index.html` has a live and a simulated example.
+
+Links also work without the script: `git0://install/owner/repo` is registered with the OS on Linux and Windows, and `http://127.0.0.1:47100/install?repo=owner/repo` works everywhere.
+
+## What it installs
+
+| OS | Preferred asset, in order | Result |
+| --- | --- | --- |
+| Linux | `.AppImage`, `.deb`, `.rpm`, `.tar.gz`, bare binary | AppImage and binaries go to `~/.git0/apps`; `.deb`/`.rpm` install through the desktop's password prompt (`pkexec`) |
+| macOS | `.dmg`, `.pkg`, `.zip`/`.tar.gz` | The `.app` is copied to `~/Applications`; a `.pkg` opens Installer |
+| Windows | setup `.exe`, `.msi`, `.zip` | The installer runs with its own UI; a portable `.zip` is extracted to `~/.git0/apps` |
+
+Asset names are matched on whole words, so `darwin` is never mistaken for `win`. An exact CPU match beats an unlabelled build, and an unlabelled build beats Rosetta or 32-bit fallbacks. Checksums, signatures and source archives are never picked. A command-line tool is installed but not launched, because it would start with no terminal attached.
+
+## Security
+
+Any website can ask, but only you can say yes. The first install of a repository opens a git0 page from `127.0.0.1` asking you to allow it, and the website cannot answer that prompt for you: the page carries a one-time token, is served without CORS headers so other sites can't read it, and refuses to be framed. Tick "Always allow" to skip the prompt for that repository next time (stored in `~/.git0/service.json`). The service listens on loopback only, rejects requests whose `Host` isn't loopback (DNS rebinding), and caps pending prompts at five.
+
+## HTTP API
+
+| Route | Returns |
+| --- | --- |
+| `GET /health` | `{ ok, name: "git0", version, os, arch }` |
+| `POST /install` `{ "repo": "owner/repo" }` | the job, plus `statusUrl` and `approveUrl` |
+| `GET /status/:id` | `status` (`awaiting-approval`, `resolving`, `downloading`, `installing`, `launching`, `done`, `error`, `denied`), `progress` 0–1, `receivedBytes`, `totalBytes`, `asset`, `tag`, `installedPath`, `launched`, `error` |
+| `GET /jobs` | every job |
+

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "git0",
     "description": "CLI tool to search GitHub repositories, download source & releases for your system, and instantly set up, then install dependencies and open code editor.",
-    "version": "0.3.66",
+    "version": "0.3.68",
     "author": "vtempest",
     "scripts": {
         "build": "bun build src/cli.ts --outdir dist --target node --format esm --sourcemap",

package/src/args.ts

@@ -16,6 +16,13 @@ export interface Flags {
   historyOnly: boolean;
   /** `--mirror` — use `--mirror` rather than `--bare` when cloning history. */
   mirror: boolean;
+  /**
+   * `--service[=run|install|uninstall|status]` — the background install
+   * service. Bare `--service` runs it in the foreground.
+   */
+  service?: 'run' | 'install' | 'uninstall' | 'status';
+  /** `--port=<n>` — the port the service listens on. */
+  port?: number;
 }
 
 /**
@@ -51,6 +58,9 @@ export function parseArgs(argv: string[]): { positional: string[]; flags: Flags
     else if (name === 'history' || name === 'git') flags.history = true;
     else if (name === 'history-only' || name === 'git-only') flags.historyOnly = true;
     else if (name === 'mirror') flags.mirror = true;
+    else if (name === 'service' && ['', 'run', 'install', 'uninstall', 'status'].includes(value)) {
+      flags.service = (value || 'run') as Flags['service'];
+    } else if (name === 'port' && /^\d+$/.test(value)) flags.port = Number(value);
     else console.log(chalk.yellow(`Ignoring unknown flag: ${arg}`));
   }
 

package/src/cli.ts

@@ -10,6 +10,8 @@ import { attachGitHistoryLazily, cloneHistoryOnly } from './history.js';
 import { parseArgs, type Flags } from './args.js';
 import { getAvailableDirectoryName } from './download.js';
 import { printLogo } from './utils.js';
+import { runServiceCommand } from './service/index.js';
+import pkg from '../package.json' with { type: 'json' };
 import type { SearchResult } from './types.js';
 
 const Github = new GithubAPI({ debug: false });
@@ -185,11 +187,17 @@ async function handleRepoDownload(selectedRepo: SearchResult, flags: Flags): Pro
  *
  * // Search:
  * //   git0 react template starter
+ *
+ * // Background install service for website download buttons:
+ * //   git0 --service=install
+ * //   git0 git0://install/owner/repo
  */
 async function main(): Promise<void> {
   printLogo();
 
   const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (await runServiceCommand(positional, flags, pkg.version)) return;
+
   if (!positional.length) {
     console.log(chalk.yellow('Usage: git0 <github-url | owner/repo[/path] | search-query>'));
     console.log(chalk.gray('  --path=<path>   download only that folder or file'));
@@ -197,6 +205,7 @@ async function main(): Promise<void> {
     console.log(chalk.gray('  --history       also fetch .git history, in the background'));
     console.log(chalk.gray('  --history-only  clone only the history, no working files'));
     console.log(chalk.gray('  --mirror        keep every ref when cloning history'));
+    console.log(chalk.gray('  --service[=install|uninstall|status]  background install service for download buttons'));
     process.exit(1);
   }
 

package/src/service/assets.ts

@@ -0,0 +1,260 @@
+import type { PlatformInfo } from '../types.js';
+
+/**
+ * How a downloaded release asset gets onto the machine. Read off the file
+ * name alone, so it can be decided before a byte is downloaded.
+ */
+export type InstallKind =
+  | 'appimage'  // Linux: chmod +x, run in place
+  | 'deb'       // Linux: dpkg via pkexec (graphical sudo prompt)
+  | 'rpm'       // Linux: rpm via pkexec
+  | 'dmg'       // macOS: mount, copy the .app into ~/Applications
+  | 'pkg'       // macOS: hand to Installer.app
+  | 'exe'       // Windows: run it — installer or portable app
+  | 'msi'       // Windows: msiexec /i
+  | 'archive'   // any OS: extract, then find something to launch
+  | 'binary';   // bare executable: chmod +x, keep in the apps folder
+
+/** A release asset chosen for this machine, with how to install it. */
+export interface PickedAsset {
+  name: string;
+  url: string;
+  size: number;
+  tag: string;
+  kind: InstallKind;
+}
+
+/** The fields of a GitHub release this module reads. */
+export interface RawRelease {
+  tag_name: string;
+  draft?: boolean;
+  prerelease?: boolean;
+  assets?: Array<{ name: string; size: number; browser_download_url: string }>;
+}
+
+/** Files attached to releases that are never the thing to install. */
+const NOT_INSTALLABLE =
+  /(\.(sha\d*|sha256sum|md5|sig|asc|pem|crt|txt|json|ya?ml|blockmap|sbom|spdx|intoto\.jsonl|zsync|sym|pdb|dSYM\.zip)$)|checksum|sha256sums|(^|[-_.])src([-_.]|$)|source/i;
+
+/**
+ * Splits a file name into lowercase tokens on anything that is not a letter or
+ * digit. Matching whole tokens rather than substrings is the point: the
+ * substring `win` is inside `darwin`, and `arm` is inside `alarm`.
+ */
+function tokens(name: string): Set<string> {
+  return new Set(name.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+}
+
+/**
+ * Which operating system an asset targets, judged by whole-word keywords and
+ * by extension. Returns `'any'` when nothing says, and `'ambiguous'` when the
+ * name names more than one OS (e.g. a combined `win-mac-linux.zip`).
+ *
+ * @example
+ * assetOs('app-darwin-arm64.tar.gz'); // → 'macos' (not 'windows' — `darwin` ≠ `win`)
+ * assetOs('app_1.0_amd64.deb');       // → 'linux'
+ * assetOs('app.jar');                 // → 'any'
+ */
+export function assetOs(name: string): 'windows' | 'macos' | 'linux' | 'any' | 'ambiguous' {
+  const lower = name.toLowerCase();
+  const t = tokens(name);
+  const has = (...words: string[]) => words.some(w => t.has(w));
+
+  const hits: Array<'windows' | 'macos' | 'linux'> = [];
+  if (has('win', 'windows', 'win32', 'win64', 'msvc', 'mingw') || /\.(exe|msi|msix|appx)$/.test(lower)) {
+    hits.push('windows');
+  }
+  if (has('mac', 'macos', 'darwin', 'osx', 'apple', 'macosx') || /\.(dmg|pkg)$/.test(lower)) {
+    hits.push('macos');
+  }
+  if (has('linux', 'ubuntu', 'debian', 'fedora', 'musl', 'gnu') || /\.(deb|rpm|appimage|snap|flatpak)$/.test(lower)) {
+    hits.push('linux');
+  }
+
+  if (hits.length === 1) return hits[0];
+  return hits.length === 0 ? 'any' : 'ambiguous';
+}
+
+/**
+ * Which CPU architecture an asset targets. `'unknown'` when the name does not
+ * say, which in practice usually means x86_64 — so it is allowed, and ranked
+ * below an exact match.
+ *
+ * @example
+ * assetArch('fzf-0.55.0-linux_arm64.tar.gz'); // → 'arm64'
+ * assetArch('app-x86_64.AppImage');           // → 'x86_64'
+ * assetArch('App-universal.dmg');             // → 'universal'
+ */
+export function assetArch(name: string): string {
+  const n = name.toLowerCase();
+  if (/universal/.test(n)) return 'universal';
+  if (/aarch64|arm64/.test(n)) return 'arm64';
+  if (/armv[67]|armhf|armel|(^|[^a-z])arm([^a-z0-9]|$)/.test(n)) return 'arm';
+  if (/x86[_-]64|amd64|x64|win64/.test(n)) return 'x86_64';
+  if (/i[36]86|x86[_-]32|ia32|win32|(^|[^a-z0-9])386([^0-9]|$)|(^|[^a-z0-9])x86([^_0-9-]|$)/.test(n)) return 'i386';
+  return 'unknown';
+}
+
+/**
+ * Reads the install kind from the file name.
+ *
+ * @example
+ * installKind('Obsidian-1.6.7.AppImage'); // → 'appimage'
+ * installKind('app.tar.gz');              // → 'archive'
+ * installKind('ripgrep');                 // → 'binary'
+ */
+export function installKind(name: string): InstallKind | null {
+  const n = name.toLowerCase();
+  if (n.endsWith('.appimage')) return 'appimage';
+  if (n.endsWith('.deb')) return 'deb';
+  if (n.endsWith('.rpm')) return 'rpm';
+  if (n.endsWith('.dmg')) return 'dmg';
+  if (n.endsWith('.pkg')) return 'pkg';
+  if (n.endsWith('.exe')) return 'exe';
+  if (n.endsWith('.msi')) return 'msi';
+  if (/\.(zip|tar\.gz|tgz|tar\.xz|txz|tar\.bz2|tbz2?|tar\.zst|tar)$/.test(n)) return 'archive';
+  // No extension at all, or only a version-ish suffix: a bare executable.
+  if (!/\.[a-z][a-z0-9]{0,4}$/.test(n)) return 'binary';
+  return null;
+}
+
+/**
+ * How much each install kind is preferred on each OS. Higher wins. A kind
+ * missing from an OS's table cannot be installed there.
+ *
+ * The order favours what installs and launches without a terminal: an
+ * AppImage over a `.deb` (no root), a `.dmg` over a `.zip`, a setup `.exe`
+ * over a portable `.zip`.
+ */
+const KIND_SCORE: Record<string, Partial<Record<InstallKind, number>>> = {
+  linux:   { appimage: 40, deb: 30, rpm: 25, archive: 20, binary: 15 },
+  macos:   { dmg: 40, pkg: 35, archive: 25, binary: 15 },
+  windows: { exe: 40, msi: 35, archive: 20 },
+};
+
+/**
+ * Scores one asset for this machine, or returns `null` when it cannot run
+ * here at all — wrong OS, wrong architecture, or not an installable file.
+ *
+ * @internal
+ */
+export function scoreAsset(name: string, platform: PlatformInfo): number | null {
+  if (NOT_INSTALLABLE.test(name)) return null;
+
+  const kind = installKind(name);
+  if (!kind) return null;
+
+  const kindScore = KIND_SCORE[platform.os]?.[kind];
+  if (kindScore === undefined) return null;
+
+  const os = assetOs(name);
+  if (os === 'ambiguous') return null;
+  if (os !== 'any' && os !== platform.os) return null;
+
+  const arch = assetArch(name);
+  let archScore: number;
+  if (arch === platform.arch) archScore = 100;
+  else if (arch === 'universal') archScore = 90;
+  // Unlabelled builds are x86_64 by convention (electron-builder names its
+  // x64 AppImage `App-1.0.AppImage`), so on x86_64 that is nearly a match;
+  // anywhere else it is a guess.
+  else if (arch === 'unknown') archScore = platform.arch === 'x86_64' ? 95 : 50;
+  // Apple Silicon runs x86_64 builds under Rosetta, and 64-bit Windows runs
+  // 32-bit ones — worse than native, better than nothing.
+  else if (platform.os === 'macos' && platform.arch === 'arm64' && arch === 'x86_64') archScore = 10;
+  else if (platform.os === 'windows' && platform.arch === 'x86_64' && arch === 'i386') archScore = 10;
+  else return null;
+
+  // An asset that names its OS is a surer bet than one that names nothing.
+  const osScore = os === platform.os ? 5 : 0;
+
+  return archScore + kindScore + osScore;
+}
+
+/**
+ * Picks the one release asset to install on this machine.
+ *
+ * Walks releases newest first, skipping drafts and — unless nothing else has a
+ * match — pre-releases, and returns the best-scoring asset of the first
+ * release that has any match at all. A newer release is always preferred over
+ * a better-packaged older one.
+ *
+ * @param releases - `GET /repos/{owner}/{repo}/releases`, newest first.
+ * @param platform - From `getCurrentPlatform()`.
+ * @returns The chosen asset, or `null` when no release ships one for this
+ *   OS/arch.
+ *
+ * @example
+ * pickAsset(releases, { os: 'linux', arch: 'x86_64', … });
+ * // → { name: 'app-1.2.0-x86_64.AppImage', kind: 'appimage', tag: 'v1.2.0', … }
+ */
+export function pickAsset(releases: RawRelease[], platform: PlatformInfo): PickedAsset | null {
+  const published = releases.filter(r => !r.draft);
+  const stable = published.filter(r => !r.prerelease);
+
+  for (const pool of [stable, published]) {
+    for (const release of pool) {
+      let best: PickedAsset | null = null;
+      let bestScore = -1;
+
+      for (const asset of release.assets ?? []) {
+        const score = scoreAsset(asset.name, platform);
+        if (score === null || score <= bestScore) continue;
+        bestScore = score;
+        best = {
+          name: asset.name,
+          url: asset.browser_download_url,
+          size: asset.size,
+          tag: release.tag_name,
+          kind: installKind(asset.name)!,
+        };
+      }
+
+      if (best) return best;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Accepts the forms a download button might pass and reduces them to
+ * `owner/repo`. Anything else is rejected — this string ends up in a GitHub
+ * API path, so it is validated rather than trusted.
+ *
+ * @example
+ * normalizeRepoSlug('https://github.com/junegunn/fzf/releases'); // → 'junegunn/fzf'
+ * normalizeRepoSlug('junegunn/fzf.git');                         // → 'junegunn/fzf'
+ * normalizeRepoSlug('../../etc/passwd');                         // → null
+ */
+export function normalizeRepoSlug(input: string | null | undefined): string | null {
+  if (!input) return null;
+  let s = input.trim();
+  s = s.replace(/^(https?:\/\/)?(www\.)?github\.com\//i, '');
+  s = s.replace(/^git@github\.com:/i, '');
+  const [owner, repo] = s.split(/[/?#]/);
+  if (!owner || !repo) return null;
+  const name = repo.replace(/\.git$/i, '');
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(owner)) return null;
+  if (!/^[A-Za-z0-9._-]{1,100}$/.test(name) || name === '.' || name === '..') return null;
+  return `${owner}/${name}`;
+}
+
+/**
+ * Reads the repository out of a `git0://` link, the custom URL scheme the
+ * service registers with the OS.
+ *
+ * @example
+ * parseSchemeUrl('git0://install/junegunn/fzf');      // → 'junegunn/fzf'
+ * parseSchemeUrl('git0://install?repo=junegunn/fzf'); // → 'junegunn/fzf'
+ * parseSchemeUrl('git0://junegunn/fzf');              // → 'junegunn/fzf'
+ */
+export function parseSchemeUrl(link: string): string | null {
+  const m = link.match(/^git0:\/{0,2}(.*)$/i);
+  if (!m) return null;
+  let rest = m[1];
+  const query = rest.match(/[?&]repo=([^&#]+)/);
+  if (query) return normalizeRepoSlug(decodeURIComponent(query[1]));
+  rest = rest.replace(/^install\/?/i, '').replace(/[?#].*$/, '');
+  return normalizeRepoSlug(decodeURIComponent(rest));
+}

package/src/service/client.ts

@@ -0,0 +1,61 @@
+import { shell } from '../utils.js';
+import { openCommand } from './installer.js';
+import { DEFAULT_PORT } from './server.js';
+
+const base = (port: number) => `http://127.0.0.1:${port}`;
+
+/** True when a git0 service answers on `port`. */
+export async function isServiceRunning(port = DEFAULT_PORT, fetchImpl: typeof fetch = fetch): Promise<boolean> {
+  try {
+    const res = await fetchImpl(`${base(port)}/health`, { signal: AbortSignal.timeout(800) });
+    return res.ok && (await res.json())?.name === 'git0';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Starts the service in the background when it is not already up, and waits
+ * for it to answer. Used by the `git0://` handler so a link works even before
+ * `--service=install` has been run.
+ */
+export async function ensureService(runtime: string, script: string, port = DEFAULT_PORT): Promise<boolean> {
+  if (await isServiceRunning(port)) return true;
+  const child = shell.spawn(runtime, [script, '--service', `--port=${port}`], { detached: true, stdio: 'ignore' }) as any;
+  child?.on?.('error', () => { /* reported below as "could not start" */ });
+  child?.unref?.();
+  for (let i = 0; i < 20; i++) {
+    await new Promise(r => setTimeout(r, 250));
+    if (await isServiceRunning(port)) return true;
+  }
+  return false;
+}
+
+/**
+ * Hands an install request to the running service and opens its page in the
+ * default browser — the approval prompt, or the progress bar for a trusted repo.
+ */
+export async function requestInstall(repo: string, port = DEFAULT_PORT): Promise<{ id: string; jobUrl: string }> {
+  const res = await fetch(`${base(port)}/install`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ repo }),
+  });
+  const body = await res.json();
+  if (!res.ok) throw new Error(body.error ?? `Service returned HTTP ${res.status}`);
+  const open = openCommand(body.jobUrl);
+  // On Linux `openCommand` runs the target itself; a URL needs xdg-open.
+  const { cmd, args } = process.platform === 'linux' ? { cmd: 'xdg-open', args: [body.jobUrl] } : open;
+  try {
+    const child = shell.spawn(cmd, args, { detached: true, stdio: 'ignore' }) as any;
+    child?.on?.('error', () => { /* no browser opener — the caller prints the URL */ });
+    child?.unref?.();
+  } catch { /* no browser — the URL is printed by the caller */ }
+  return { id: body.id, jobUrl: body.jobUrl };
+}
+
+/** Every job the running service knows about. */
+export async function listJobs(port = DEFAULT_PORT): Promise<any[]> {
+  const res = await fetch(`${base(port)}/jobs`);
+  return res.json();
+}

package/src/service/index.ts

@@ -0,0 +1,77 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import type { Flags } from '../args.js';
+import { parseSchemeUrl } from './assets.js';
+import { ensureService, isServiceRunning, listJobs, requestInstall } from './client.js';
+import { DEFAULT_PORT, startService } from './server.js';
+import { installSystemService, uninstallSystemService } from './system-service.js';
+
+export { DEFAULT_PORT, createServiceServer, startService, JobManager, TrustStore } from './server.js';
+export { pickAsset, normalizeRepoSlug, parseSchemeUrl } from './assets.js';
+
+/** The runtime and script this process was started with — what the service files re-run. */
+function selfCommand(): { runtime: string; script: string } {
+  const script = process.argv[1] ? fs.realpathSync(path.resolve(process.argv[1])) : '';
+  return { runtime: process.execPath, script };
+}
+
+/**
+ * Handles `--service[=…]` and `git0://` links. Returns `true` when it handled
+ * the invocation, so `main()` stops there.
+ *
+ * @example
+ * // git0 --service              → run the service in the foreground
+ * // git0 --service=install      → register it to start at login, and start it
+ * // git0 --service=uninstall    → remove it
+ * // git0 --service=status       → is it up, and what is it doing
+ * // git0 git0://install/owner/repo  → what the OS runs when a git0:// link is clicked
+ */
+export async function runServiceCommand(positional: string[], flags: Flags, version?: string): Promise<boolean> {
+  const port = flags.port ?? DEFAULT_PORT;
+  const link = positional.find(p => /^git0:/i.test(p));
+
+  if (link) {
+    const repo = parseSchemeUrl(link);
+    if (!repo) throw new Error(`Not a git0 install link: ${link}`);
+    const self = selfCommand();
+    if (!(await ensureService(self.runtime, self.script, port))) {
+      throw new Error('Could not start the git0 service');
+    }
+    const { jobUrl } = await requestInstall(repo, port);
+    console.log(chalk.green(`Install of ${repo} requested — ${jobUrl}`));
+    return true;
+  }
+
+  if (!flags.service) return false;
+
+  switch (flags.service) {
+    case 'run': {
+      const { port: bound } = await startService({ port, version });
+      console.log(chalk.green(`git0 service listening on http://127.0.0.1:${bound}`));
+      return true;
+    }
+    case 'install': {
+      for (const line of installSystemService({ ...selfCommand(), port })) console.log(chalk.green(`✅ ${line}`));
+      return true;
+    }
+    case 'uninstall': {
+      for (const line of uninstallSystemService()) console.log(chalk.green(`✅ ${line}`));
+      return true;
+    }
+    case 'status': {
+      if (!(await isServiceRunning(port))) {
+        console.log(chalk.yellow(`git0 service is not running on port ${port}`));
+        process.exitCode = 1;
+        return true;
+      }
+      console.log(chalk.green(`git0 service is running on http://127.0.0.1:${port}`));
+      for (const j of await listJobs(port)) {
+        const pct = `${Math.round(j.progress * 100)}%`.padStart(4);
+        console.log(`  ${pct}  ${j.status.padEnd(17)} ${j.repo}${j.error ? chalk.red(`  ${j.error}`) : ''}`);
+      }
+      return true;
+    }
+  }
+  return false;
+}