shadow-git 1.1.0 → 1.1.1

package/CLAUDE.md

@@ -43,6 +43,7 @@ src/
     hooks.ts                # Install/uninstall pre-commit hooks
     errors.ts               # Custom error classes (SgitError hierarchy)
     gitignore.ts            # Disable/enable .gitignore files during sgit operations
+    update-check.ts         # Daily npm registry check (detached worker) and update notice
   utils/
     logger.ts               # Color-coded stdout/stderr logging
     process.ts              # Child process execution
@@ -56,5 +57,7 @@ src/
 - Shadow repo exclude uses a deny-all + allow-list pattern (`*` then `!path`)
 - Error classes extend `SgitError`; the CLI catches these and prints the message
 - Hidden `debug` commands (`sgit debug <cmd>`) are registered with `{ hidden: true }` so they don't appear in `sgit --help`. They are only visible via `sgit debug --help`. Debug commands manage their own gitignore guard (the CLI-level guard is skipped for them). No tests are written for debug commands.
+- **Update check:** `setupUpdateNotifier` (`src/core/update-check.ts`) runs at the start of every interactive invocation — stdout and stderr must both be TTYs; it is skipped for the hook-driven `track verify` and when `NO_UPDATE_NOTIFIER` is set. The command's own process never touches the network: when the last successful check is more than a day old, the CLI re-spawns itself detached with the `__update-check` argument, and that worker writes the registry's `latest` version to `update-check.json` in `$XDG_CACHE_HOME/shadow-git` (default `~/.cache/shadow-git`). The notice is printed from a `process.on('exit')` listener on every run for as long as the cached `latest` is newer than the installed version; only the registry check is limited to once a day. sgit processes started underneath another sgit (the shadow hooks run `sgit track sync`) see `SGIT_UPDATE_NOTICE_HANDLED` in their environment and stay quiet, so one command prints the notice once. Everything on this path fails silently: a failed check records nothing, so the next invocation tries again, and the exit listener must never throw — a throwing `'exit'` listener keeps later ones (the gitignore guard's cleanup) from running.
+- The CLI version (`sgit --version`, and the "current" side of the update notice) is read at runtime from `package.json` by `readVersion` in `src/cli.ts` — it is not hardcoded anywhere.
 - **HARD RULE — gitignore revert guarantee:** `.gitignore` files inside sgit-tracked directories are temporarily renamed to `.gitignore.sgit-parked` during sgit command execution (via `setupGitignoreGuard` in `src/core/gitignore.ts`). **The rename MUST always be reverted** when the command ends — whether it succeeds, fails, is cancelled (Ctrl+C), or receives SIGTERM. The guard uses `try/finally`, signal handlers, and `process.on('exit')` to ensure this. Any new code that executes sgit operations must use the guard or equivalent cleanup guarantees. Pre-commit hooks verify no `.gitignore.sgit-parked` files exist at commit time.
 - **Swap-mode exception to the gitignore revert rule:** while swap mode is active (marker `.git.sgit-parked` present), `.gitignore.sgit-parked` files are **expected to persist** across commands — they stay disabled from `sgit track swap` until `sgit track unswap`. To prevent drift, `disableGitignores`, `enableGitignores`, and `setupGitignoreGuard` refuse to run (throwing `SwapModeActiveError`) whenever `isSwapModeSync(root)` is true. The swap and unswap commands call these helpers only outside the swap window (swap calls `disableGitignores` before creating the marker; unswap calls `enableGitignores` after removing it), so the refusal never blocks the legitimate transitions. The CLI-level gitignore guard is already skipped for `swap`/`unswap` and whenever swap mode is active.

package/README.md

@@ -54,6 +54,19 @@ Any non-track command is forwarded to git using the shadow repository (e.g. `sgi
 - **`.sgit/info/exclude`** — Configured to only see shadow-tracked files
 - **Pre-commit hooks** — Verify that staged files belong to the correct repository
 
+## Update Notifications
+
+Once a day, `sgit` checks the npm registry for a newer version of shadow-git. When one is available, a short note is printed after your command's output:
+
+```
+Update available: shadow-git 1.1.0 → 1.2.0
+Please run 'npm install -g shadow-git' to update.
+```
+
+It is only a note — nothing is installed or blocked. It is shown on every run until you update. The check runs in a background process, so commands never wait on the network. If the registry cannot be reached, the check fails silently and is tried again the next time you run `sgit`.
+
+All of this happens only in an interactive terminal: nothing is checked or printed when output is piped or redirected. To turn the check off entirely, set `NO_UPDATE_NOTIFIER=1`.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { fileURLToPath } from "url";
 import { Command as Command2 } from "commander";
 
 // src/core/repository.ts
@@ -273,6 +275,15 @@ function swapModeBanner() {
   process.stderr.write(`${YELLOW}${msg}${RESET}
 `);
 }
+function updateNotice(current, latest) {
+  const msg = [
+    `Update available: shadow-git ${current} \u2192 ${latest}`,
+    "Please run 'npm install -g shadow-git' to update."
+  ].join("\n");
+  process.stderr.write(`
+${CYAN}${msg}${RESET}
+`);
+}
 
 // src/commands/track/init.ts
 import { join as join5 } from "path";
@@ -1912,10 +1923,174 @@ function wrapAction2(fn) {
   };
 }
 
+// src/core/update-check.ts
+import { spawn } from "child_process";
+import {
+  mkdirSync,
+  readFileSync as readFileSync2,
+  statSync,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { homedir as homedir2 } from "os";
+import { isAbsolute, join as join14 } from "path";
+var PACKAGE_NAME = "shadow-git";
+var DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${PACKAGE_NAME}/dist-tags`;
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1e4;
+var LOCK_STALE_MS = 6e4;
+var STATE_FILE = "update-check.json";
+var LOCK_FILE2 = "update-check.lock";
+var VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+var UPDATE_CHECK_ARG = "__update-check";
+var HANDLED_ENV = "SGIT_UPDATE_NOTICE_HANDLED";
+function setupUpdateNotifier(currentVersion, entry, args) {
+  const nested = Boolean(process.env[HANDLED_ENV]);
+  process.env[HANDLED_ENV] = "1";
+  if (nested || !isEnabled(args)) return;
+  try {
+    const dir = getCacheDir();
+    if (isCheckDue(readState(dir)) && acquireLock(dir)) {
+      spawnWorker(dir, entry);
+    }
+    process.on("exit", () => showNotice(dir, currentVersion));
+  } catch {
+  }
+}
+async function runUpdateCheckWorker() {
+  try {
+    const dir = getCacheDir();
+    try {
+      const latest = await fetchLatestVersion();
+      if (latest !== void 0) {
+        writeState(dir, { checkedAt: Date.now(), latest });
+      }
+    } finally {
+      releaseLock(dir);
+    }
+  } catch {
+  }
+}
+function isNewerVersion(latest, current) {
+  const a = VERSION_RE.exec(latest);
+  const b = VERSION_RE.exec(current);
+  if (!a || !b) return false;
+  for (let i = 1; i <= 3; i++) {
+    const diff = Number(a[i]) - Number(b[i]);
+    if (diff !== 0) return diff > 0;
+  }
+  return a[4] === void 0 && b[4] !== void 0;
+}
+function getCacheDir() {
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg && isAbsolute(xdg) ? xdg : join14(homedir2(), ".cache");
+  return join14(base, PACKAGE_NAME);
+}
+function isEnabled(args) {
+  if (!process.stdout.isTTY || !process.stderr.isTTY) return false;
+  if (process.env.NO_UPDATE_NOTIFIER) return false;
+  if (args[0] === "track" && args[1] === "verify") return false;
+  return true;
+}
+function isCheckDue(state) {
+  if (!state) return true;
+  const age = Date.now() - state.checkedAt;
+  return age < 0 || age >= DAY_MS;
+}
+function showNotice(dir, currentVersion) {
+  try {
+    const latest = readState(dir)?.latest;
+    if (latest !== void 0 && isNewerVersion(latest, currentVersion)) {
+      updateNotice(currentVersion, latest);
+    }
+  } catch {
+  }
+}
+function spawnWorker(dir, entry) {
+  try {
+    const child = spawn(process.execPath, [entry, UPDATE_CHECK_ARG], {
+      cwd: dir,
+      // not the user's repo — a lingering cwd can block deleting it
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.on("error", () => releaseLock(dir));
+    child.unref();
+  } catch {
+    releaseLock(dir);
+  }
+}
+async function fetchLatestVersion() {
+  const res = await fetch(DIST_TAGS_URL, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  });
+  if (!res.ok) return void 0;
+  const tags = await res.json();
+  return typeof tags?.latest === "string" ? tags.latest : void 0;
+}
+function readState(dir) {
+  try {
+    const data = JSON.parse(
+      readFileSync2(join14(dir, STATE_FILE), "utf-8")
+    );
+    if (typeof data?.checkedAt !== "number" || typeof data.latest !== "string") {
+      return void 0;
+    }
+    return { checkedAt: data.checkedAt, latest: data.latest };
+  } catch {
+    return void 0;
+  }
+}
+function writeState(dir, state) {
+  writeFileSync2(join14(dir, STATE_FILE), JSON.stringify(state, null, 2) + "\n");
+}
+function acquireLock(dir) {
+  const lockPath = join14(dir, LOCK_FILE2);
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync2(lockPath, String(process.pid), { flag: "wx" });
+    return true;
+  } catch {
+  }
+  try {
+    const age = Math.abs(Date.now() - statSync(lockPath).mtimeMs);
+    if (age < LOCK_STALE_MS) return false;
+    writeFileSync2(lockPath, String(process.pid));
+    return true;
+  } catch {
+    return false;
+  }
+}
+function releaseLock(dir) {
+  try {
+    unlinkSync2(join14(dir, LOCK_FILE2));
+  } catch {
+  }
+}
+
 // src/cli.ts
 var COMMANDER_COMMANDS = /* @__PURE__ */ new Set(["track", "debug"]);
+function readVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync3(new URL("../package.json", import.meta.url), "utf-8")
+    );
+    return typeof pkg.version === "string" ? pkg.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function run() {
   const args = process.argv.slice(2);
+  if (args[0] === UPDATE_CHECK_ARG) {
+    await runUpdateCheckWorker();
+    process.exit(0);
+  }
+  const version = readVersion();
+  if (version) {
+    setupUpdateNotifier(version, fileURLToPath(import.meta.url), args);
+  }
   let swapActive = false;
   try {
     const root = await findRoot();
@@ -1944,7 +2119,7 @@ async function run() {
   }
   try {
     if (args.length === 0 || COMMANDER_COMMANDS.has(args[0]) || args[0].startsWith("-")) {
-      const program = new Command2("sgit").description("Shadow Git \u2014 a secondary git repository for your project").version("0.1.0");
+      const program = new Command2("sgit").description("Shadow Git \u2014 a secondary git repository for your project").version(version ?? "unknown");
       registerTrackCommands(program);
       registerDebugCommands(program);
       program.addHelpText(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadow-git",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A secondary git repository for tracking files excluded from your main repo",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { findRoot, validateShadowRepo } from './core/repository.js';
 import { forwardToGit } from './commands/forward.js';
@@ -8,13 +10,43 @@ import { readManifest } from './core/manifest.js';
 import { setupGitignoreGuard } from './core/gitignore.js';
 import { isSwapMode, assertConsistentState } from './core/swap-mode.js';
 import { SwapModeCorruptError } from './core/errors.js';
+import {
+  UPDATE_CHECK_ARG,
+  runUpdateCheckWorker,
+  setupUpdateNotifier,
+} from './core/update-check.js';
 import * as logger from './utils/logger.js';
 
 const COMMANDER_COMMANDS = new Set(['track', 'debug']);
 
+// package.json sits one directory above this file, both as src/cli.ts and as
+// the built dist/cli.js. Read at runtime so it is always the installed version.
+function readVersion(): string | undefined {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL('../package.json', import.meta.url), 'utf-8'),
+    );
+    return typeof pkg.version === 'string' ? pkg.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 async function run(): Promise<void> {
   const args = process.argv.slice(2);
 
+  // Detached process started by setupUpdateNotifier — it only refreshes the
+  // cached registry answer and never runs a command
+  if (args[0] === UPDATE_CHECK_ARG) {
+    await runUpdateCheckWorker();
+    process.exit(0);
+  }
+
+  const version = readVersion();
+  if (version) {
+    setupUpdateNotifier(version, fileURLToPath(import.meta.url), args);
+  }
+
   // Detect swap mode (and surface any inconsistent state) up front
   let swapActive = false;
   try {
@@ -67,7 +99,7 @@ async function run(): Promise<void> {
     ) {
       const program = new Command('sgit')
         .description('Shadow Git — a secondary git repository for your project')
-        .version('0.1.0');
+        .version(version ?? 'unknown');
 
       registerTrackCommands(program);
       registerDebugCommands(program);

package/src/core/update-check.ts

@@ -0,0 +1,214 @@
+import { spawn } from 'node:child_process';
+import {
+  mkdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import * as logger from '../utils/logger.js';
+
+const PACKAGE_NAME = 'shadow-git';
+const DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${PACKAGE_NAME}/dist-tags`;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+// A lock older than this was left behind by a worker that died mid-check
+const LOCK_STALE_MS = 60_000;
+const STATE_FILE = 'update-check.json';
+const LOCK_FILE = 'update-check.lock';
+
+// x.y.z with an optional prerelease and build suffix
+const VERSION_RE =
+  /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+// First CLI argument of the detached process that asks the registry
+export const UPDATE_CHECK_ARG = '__update-check';
+
+// Tells sgit processes started underneath this one (git hooks run
+// `sgit track sync`) that the outermost invocation takes care of the notice
+const HANDLED_ENV = 'SGIT_UPDATE_NOTICE_HANDLED';
+
+interface UpdateState {
+  checkedAt: number; // last time the registry answered (ms since epoch)
+  latest: string; // version behind the `latest` dist-tag at that time
+}
+
+// --- Public API ---
+
+/**
+ * Called once per CLI invocation. Hands the daily registry check to a detached
+ * process, so the command itself never waits on the network, and prints the
+ * update notice when the command ends — on every run for as long as a newer
+ * version is known.
+ */
+export function setupUpdateNotifier(
+  currentVersion: string,
+  entry: string,
+  args: string[],
+): void {
+  const nested = Boolean(process.env[HANDLED_ENV]);
+  process.env[HANDLED_ENV] = '1';
+  if (nested || !isEnabled(args)) return;
+  try {
+    const dir = getCacheDir();
+    if (isCheckDue(readState(dir)) && acquireLock(dir)) {
+      spawnWorker(dir, entry);
+    }
+    process.on('exit', () => showNotice(dir, currentVersion));
+  } catch {
+    // The update check must never get in the way of the actual command
+  }
+}
+
+/**
+ * Body of the detached process: asks the npm registry for the latest version
+ * and records the answer. Any failure (offline, registry down, timeout) is
+ * silent and records nothing, so the next invocation simply checks again.
+ */
+export async function runUpdateCheckWorker(): Promise<void> {
+  try {
+    const dir = getCacheDir();
+    try {
+      const latest = await fetchLatestVersion();
+      if (latest !== undefined) {
+        writeState(dir, { checkedAt: Date.now(), latest });
+      }
+    } finally {
+      releaseLock(dir);
+    }
+  } catch {
+    // stay silent
+  }
+}
+
+export function isNewerVersion(latest: string, current: string): boolean {
+  const a = VERSION_RE.exec(latest);
+  const b = VERSION_RE.exec(current);
+  if (!a || !b) return false;
+
+  for (let i = 1; i <= 3; i++) {
+    const diff = Number(a[i]) - Number(b[i]);
+    if (diff !== 0) return diff > 0;
+  }
+  // Same x.y.z: a release is newer than its own prerelease. Two prereleases
+  // of the same version are not ordered — `latest` is never a prerelease.
+  return a[4] === undefined && b[4] !== undefined;
+}
+
+export function getCacheDir(): string {
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg && isAbsolute(xdg) ? xdg : join(homedir(), '.cache');
+  return join(base, PACKAGE_NAME);
+}
+
+// --- Internal helpers ---
+
+function isEnabled(args: string[]): boolean {
+  // Only when a person is at the terminal — pipes and scripts stay untouched
+  if (!process.stdout.isTTY || !process.stderr.isTTY) return false;
+  if (process.env.NO_UPDATE_NOTIFIER) return false;
+  // `track verify` is run by the pre-commit hooks, not typed by the user
+  if (args[0] === 'track' && args[1] === 'verify') return false;
+  return true;
+}
+
+/**
+ * True when no check has succeeded yet, the last one is at least a day old,
+ * or it is dated in the future (the clock was changed).
+ */
+function isCheckDue(state: UpdateState | undefined): boolean {
+  if (!state) return true;
+  const age = Date.now() - state.checkedAt;
+  return age < 0 || age >= DAY_MS;
+}
+
+function showNotice(dir: string, currentVersion: string): void {
+  try {
+    // Read again — the worker may have finished while the command was running
+    const latest = readState(dir)?.latest;
+    if (latest !== undefined && isNewerVersion(latest, currentVersion)) {
+      logger.updateNotice(currentVersion, latest);
+    }
+  } catch {
+    // Must not throw: an 'exit' listener that throws keeps the ones after it
+    // from running, and the gitignore guard restores .gitignore files in one
+  }
+}
+
+function spawnWorker(dir: string, entry: string): void {
+  try {
+    const child = spawn(process.execPath, [entry, UPDATE_CHECK_ARG], {
+      cwd: dir, // not the user's repo — a lingering cwd can block deleting it
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.on('error', () => releaseLock(dir));
+    child.unref();
+  } catch {
+    releaseLock(dir);
+  }
+}
+
+async function fetchLatestVersion(): Promise<string | undefined> {
+  const res = await fetch(DIST_TAGS_URL, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok) return undefined;
+
+  const tags = (await res.json()) as { latest?: unknown } | null;
+  return typeof tags?.latest === 'string' ? tags.latest : undefined;
+}
+
+function readState(dir: string): UpdateState | undefined {
+  try {
+    const data = JSON.parse(
+      readFileSync(join(dir, STATE_FILE), 'utf-8'),
+    ) as Partial<UpdateState> | null;
+    if (typeof data?.checkedAt !== 'number' || typeof data.latest !== 'string') {
+      return undefined;
+    }
+    return { checkedAt: data.checkedAt, latest: data.latest };
+  } catch {
+    // Missing or corrupt — same as never having checked
+    return undefined;
+  }
+}
+
+function writeState(dir: string, state: UpdateState): void {
+  writeFileSync(join(dir, STATE_FILE), JSON.stringify(state, null, 2) + '\n');
+}
+
+/**
+ * The lock keeps a burst of invocations from each starting their own worker.
+ * It is held from spawn until the worker exits; the worker removes it whether
+ * the check succeeded or not.
+ */
+function acquireLock(dir: string): boolean {
+  const lockPath = join(dir, LOCK_FILE);
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+    return true;
+  } catch {
+    // Already locked, or the cache directory is not writable
+  }
+  try {
+    const age = Math.abs(Date.now() - statSync(lockPath).mtimeMs);
+    if (age < LOCK_STALE_MS) return false;
+    writeFileSync(lockPath, String(process.pid)); // take over the stale lock
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function releaseLock(dir: string): void {
+  try {
+    unlinkSync(join(dir, LOCK_FILE));
+  } catch {
+    // already released
+  }
+}

package/src/utils/logger.ts

@@ -31,3 +31,11 @@ export function swapModeBanner(): void {
   ].join('\n');
   process.stderr.write(`${YELLOW}${msg}${RESET}\n`);
 }
+
+export function updateNotice(current: string, latest: string): void {
+  const msg = [
+    `Update available: shadow-git ${current} → ${latest}`,
+    "Please run 'npm install -g shadow-git' to update.",
+  ].join('\n');
+  process.stderr.write(`\n${CYAN}${msg}${RESET}\n`);
+}