shadow-git 1.0.3 → 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,4 +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.
-- **HARD RULE — gitignore revert guarantee:** `.gitignore` files inside sgit-tracked directories are temporarily renamed to `.gitignore-sgit.bat` 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.bat` files exist at commit time.
+- **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