shadow-git 1.0.3 → 1.1.1

package/src/core/swap-mode.ts

@@ -0,0 +1,83 @@
+import { access } from 'node:fs/promises';
+import { constants, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  SwapModeCorruptError,
+  InProgressGitOpError,
+} from './errors.js';
+
+export const SWAP_MARKER = '.git.sgit-parked';
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isSwapMode(root: string): Promise<boolean> {
+  return pathExists(join(root, SWAP_MARKER));
+}
+
+export function isSwapModeSync(root: string): boolean {
+  return existsSync(join(root, SWAP_MARKER));
+}
+
+export async function resolveShadowDir(root: string): Promise<string> {
+  return (await isSwapMode(root))
+    ? join(root, '.git')
+    : join(root, '.sgit');
+}
+
+export async function resolveMainDir(root: string): Promise<string> {
+  return (await isSwapMode(root))
+    ? join(root, SWAP_MARKER)
+    : join(root, '.git');
+}
+
+const IN_PROGRESS_MARKERS = [
+  'index.lock',
+  'MERGE_HEAD',
+  'CHERRY_PICK_HEAD',
+  'REVERT_HEAD',
+  'rebase-apply',
+  'rebase-merge',
+  'BISECT_LOG',
+];
+
+export async function assertNoInProgressOps(gitDir: string): Promise<void> {
+  for (const marker of IN_PROGRESS_MARKERS) {
+    if (await pathExists(join(gitDir, marker))) {
+      throw new InProgressGitOpError(gitDir, marker);
+    }
+  }
+}
+
+export async function assertConsistentState(root: string): Promise<void> {
+  const hasDisabled = await pathExists(join(root, SWAP_MARKER));
+  const hasGit = await pathExists(join(root, '.git'));
+  const hasSgit = await pathExists(join(root, '.sgit'));
+
+  if (hasDisabled && !hasGit) {
+    throw new SwapModeCorruptError(
+      [
+        `found ${SWAP_MARKER}/ but no .git/ — a swap-mode transition was interrupted.`,
+        hasSgit
+          ? `to recover: rename ${SWAP_MARKER} back to .git (.sgit is still intact).`
+          : `to recover: rename ${SWAP_MARKER} back to .git, or rename whichever of .sgit/${SWAP_MARKER} you want active to .git.`,
+      ].join('\n'),
+    );
+  }
+
+  if (hasDisabled && hasSgit) {
+    throw new SwapModeCorruptError(
+      [
+        `found both ${SWAP_MARKER}/ and .sgit/ — unexpected state.`,
+        'normally only one exists at a time.',
+        `investigate and remove the stale one before proceeding.`,
+      ].join('\n'),
+    );
+  }
+}

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

@@ -19,3 +19,23 @@ export function warn(msg: string): void {
 export function error(msg: string): void {
   process.stderr.write(`${RED}${msg}${RESET}\n`);
 }
+
+export function swapModeBanner(): void {
+  const msg = [
+    '────────────────────────────────────────────────────────────',
+    'shadow-git is in SWAP MODE',
+    'main git is parked at .git.sgit-parked; .sgit is active at .git',
+    'this mode is for IDE/tool compatibility — read-only recommended',
+    "run 'sgit track unswap' before making main-repo changes",
+    '────────────────────────────────────────────────────────────',
+  ].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`);
+}

package/tests/commands/forward.test.ts

@@ -37,19 +37,19 @@ describe('forwardToGit', () => {
     await removeTempDir(tempDir);
   });
 
-  it('forwards git commands to shadow repo and returns exit code', () => {
-    const exitCode = forwardToGit(tempDir, ['log', '--oneline']);
+  it('forwards git commands to shadow repo and returns exit code', async () => {
+    const exitCode = await forwardToGit(tempDir, ['log', '--oneline']);
     expect(exitCode).toBe(0);
   });
 
-  it('returns non-zero exit code for failing commands', () => {
-    const exitCode = forwardToGit(tempDir, ['log', '--invalid-flag-xyz']);
+  it('returns non-zero exit code for failing commands', async () => {
+    const exitCode = await forwardToGit(tempDir, ['log', '--invalid-flag-xyz']);
     expect(exitCode).not.toBe(0);
   });
 
-  it('uses .sgit as git-dir', () => {
+  it('uses .sgit as git-dir', async () => {
     // rev-parse --git-dir should show the .sgit path
-    const exitCode = forwardToGit(tempDir, ['rev-parse', '--git-dir']);
+    const exitCode = await forwardToGit(tempDir, ['rev-parse', '--git-dir']);
     expect(exitCode).toBe(0);
   });
 });

package/tests/commands/track/add.test.ts

@@ -150,17 +150,17 @@ describe('track add', () => {
     );
   });
 
-  it('rejects .gitignore-sgit.bat files', async () => {
-    await writeFile(join(tempDir, '.gitignore-sgit.bat'), 'stale\n');
-    await expect(trackAdd(['.gitignore-sgit.bat'])).rejects.toThrow(
+  it('rejects .gitignore.sgit-parked files', async () => {
+    await writeFile(join(tempDir, '.gitignore.sgit-parked'), 'stale\n');
+    await expect(trackAdd(['.gitignore.sgit-parked'])).rejects.toThrow(
       '.gitignore files are managed by sgit',
     );
   });
 
-  it('rejects nested .gitignore-sgit.bat files', async () => {
+  it('rejects nested .gitignore.sgit-parked files', async () => {
     await mkdir(join(tempDir, 'docs'), { recursive: true });
-    await writeFile(join(tempDir, 'docs', '.gitignore-sgit.bat'), 'stale\n');
-    await expect(trackAdd(['docs/.gitignore-sgit.bat'])).rejects.toThrow(
+    await writeFile(join(tempDir, 'docs', '.gitignore.sgit-parked'), 'stale\n');
+    await expect(trackAdd(['docs/.gitignore.sgit-parked'])).rejects.toThrow(
       '.gitignore files are managed by sgit',
     );
   });

package/tests/commands/track/swap.test.ts

@@ -0,0 +1,266 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  access,
+  writeFile,
+  mkdir,
+  unlink,
+  rename,
+  readFile,
+} from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import { trackInit } from '../../../src/commands/track/init';
+import { trackAdd } from '../../../src/commands/track/add';
+import { trackList } from '../../../src/commands/track/list';
+import { trackSync } from '../../../src/commands/track/sync';
+import { trackClone } from '../../../src/commands/track/clone';
+import { trackDestroy } from '../../../src/commands/track/destroy';
+import { trackSwap } from '../../../src/commands/track/swap';
+import { trackUnswap } from '../../../src/commands/track/unswap';
+import { verifyShadow, verifyMain } from '../../../src/commands/track/verify';
+import {
+  disableGitignores,
+  enableGitignores,
+  setupGitignoreGuard,
+} from '../../../src/core/gitignore';
+import {
+  isSwapMode,
+  resolveShadowDir,
+  resolveMainDir,
+  assertConsistentState,
+  SWAP_MARKER,
+} from '../../../src/core/swap-mode';
+import { swapModeBanner } from '../../../src/utils/logger';
+import {
+  AlreadySwappedError,
+  NotSwappedError,
+  SwapModeActiveError,
+  SwapModeCorruptError,
+  InProgressGitOpError,
+} from '../../../src/core/errors';
+import { execGit } from '../../../src/core/git';
+import { createTempGitRepo, removeTempDir } from '../../helpers';
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('track swap / unswap', () => {
+  let tempDir: string;
+  const originalCwd = process.cwd();
+
+  beforeEach(async () => {
+    tempDir = await createTempGitRepo();
+    process.chdir(tempDir);
+    await trackInit();
+  });
+
+  afterEach(async () => {
+    process.chdir(originalCwd);
+    await removeTempDir(tempDir);
+  });
+
+  it('swaps .git and .sgit on swap, restores on unswap', async () => {
+    await writeFile(join(tempDir, 'note.md'), 'hello');
+    await trackAdd(['note.md']);
+
+    expect(await exists(join(tempDir, '.git'))).toBe(true);
+    expect(await exists(join(tempDir, '.sgit'))).toBe(true);
+    expect(await exists(join(tempDir, SWAP_MARKER))).toBe(false);
+
+    await trackSwap();
+
+    expect(await isSwapMode(tempDir)).toBe(true);
+    expect(await exists(join(tempDir, '.git'))).toBe(true);
+    expect(await exists(join(tempDir, '.sgit'))).toBe(false);
+    expect(await exists(join(tempDir, SWAP_MARKER))).toBe(true);
+
+    // .git is now the shadow — should have .sgit.json committed
+    const lsFiles = await execGit(['ls-files'], {
+      gitDir: join(tempDir, '.git'),
+      workTree: tempDir,
+    });
+    expect(lsFiles).toContain('.sgit.json');
+
+    await trackUnswap();
+
+    expect(await isSwapMode(tempDir)).toBe(false);
+    expect(await exists(join(tempDir, '.git'))).toBe(true);
+    expect(await exists(join(tempDir, '.sgit'))).toBe(true);
+    expect(await exists(join(tempDir, SWAP_MARKER))).toBe(false);
+
+    // .git is restored to main — log should show 'initial' from createTempGitRepo
+    const mainLog = await execGit(['log', '--oneline'], {
+      gitDir: join(tempDir, '.git'),
+      workTree: tempDir,
+    });
+    expect(mainLog).toContain('initial');
+  });
+
+  it('disables gitignores inside tracked dirs while swapped', async () => {
+    await mkdir(join(tempDir, 'notes'), { recursive: true });
+    await writeFile(join(tempDir, 'notes', 'todo.md'), 'x');
+    await writeFile(join(tempDir, 'notes', '.gitignore'), '*.tmp\n');
+    await trackAdd(['notes/']);
+
+    await trackSwap();
+
+    expect(await exists(join(tempDir, 'notes', '.gitignore'))).toBe(false);
+    expect(
+      await exists(join(tempDir, 'notes', '.gitignore.sgit-parked')),
+    ).toBe(true);
+
+    await trackUnswap();
+
+    expect(await exists(join(tempDir, 'notes', '.gitignore'))).toBe(true);
+    expect(
+      await exists(join(tempDir, 'notes', '.gitignore.sgit-parked')),
+    ).toBe(false);
+  });
+
+  it('resolves shadow and main dirs correctly in both modes', async () => {
+    expect(await resolveShadowDir(tempDir)).toBe(join(tempDir, '.sgit'));
+    expect(await resolveMainDir(tempDir)).toBe(join(tempDir, '.git'));
+
+    await trackSwap();
+
+    expect(await resolveShadowDir(tempDir)).toBe(join(tempDir, '.git'));
+    expect(await resolveMainDir(tempDir)).toBe(join(tempDir, SWAP_MARKER));
+  });
+
+  it('allows other track commands while swapped', async () => {
+    await writeFile(join(tempDir, 'note.md'), 'hi');
+    await trackAdd(['note.md']);
+
+    await trackSwap();
+
+    // list
+    const paths = await trackList();
+    expect(paths).toContain('note.md');
+
+    // add a new file
+    await writeFile(join(tempDir, 'note2.md'), 'bye');
+    await trackAdd(['note2.md']);
+    expect(await trackList()).toContain('note2.md');
+
+    // sync regenerates excludes at the swapped locations
+    await trackSync();
+    const shadowExclude = await readFile(
+      join(tempDir, '.git', 'info', 'exclude'),
+      'utf-8',
+    );
+    expect(shadowExclude).toContain('!note.md');
+    expect(shadowExclude).toContain('!note2.md');
+
+    const mainExclude = await readFile(
+      join(tempDir, SWAP_MARKER, 'info', 'exclude'),
+      'utf-8',
+    );
+    expect(mainExclude).toContain('note.md');
+  });
+
+  it('swapModeBanner writes yellow banner to stderr', () => {
+    const writes: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation((chunk: unknown) => {
+        writes.push(String(chunk));
+        return true;
+      });
+
+    swapModeBanner();
+
+    spy.mockRestore();
+
+    const output = writes.join('');
+    expect(output).toContain('SWAP MODE');
+    expect(output).toContain('\x1b[33m'); // yellow
+    expect(output).toContain('\x1b[0m'); // reset
+  });
+
+  it('errors on double-enter and double-exit', async () => {
+    await trackSwap();
+    await expect(trackSwap()).rejects.toBeInstanceOf(AlreadySwappedError);
+
+    await trackUnswap();
+    await expect(trackUnswap()).rejects.toBeInstanceOf(NotSwappedError);
+  });
+
+  it('refuses init, clone, and destroy while swapped', async () => {
+    await trackSwap();
+
+    await expect(trackInit()).rejects.toBeInstanceOf(SwapModeActiveError);
+    await expect(trackClone('https://example.invalid/repo.git')).rejects.toBeInstanceOf(
+      SwapModeActiveError,
+    );
+    await expect(trackDestroy({ force: true })).rejects.toBeInstanceOf(
+      SwapModeActiveError,
+    );
+  });
+
+  it('refuses swap if main git has in-progress op', async () => {
+    await writeFile(join(tempDir, '.git', 'index.lock'), '');
+
+    await expect(trackSwap()).rejects.toBeInstanceOf(InProgressGitOpError);
+
+    // no swap happened
+    expect(await isSwapMode(tempDir)).toBe(false);
+
+    await unlink(join(tempDir, '.git', 'index.lock'));
+    await trackSwap();
+    expect(await isSwapMode(tempDir)).toBe(true);
+  });
+
+  it('detects corrupt state when .git is missing but marker exists', async () => {
+    await trackSwap();
+
+    // Simulate crash between rename steps: rename .git back away,
+    // so .git.sgit-parked exists but no .git
+    await rename(join(tempDir, '.git'), join(tempDir, '.sgit'));
+
+    await expect(assertConsistentState(tempDir)).rejects.toBeInstanceOf(
+      SwapModeCorruptError,
+    );
+  });
+
+  it('verify does not flag disabled gitignores as stale while swapped', async () => {
+    await mkdir(join(tempDir, 'notes'), { recursive: true });
+    await writeFile(join(tempDir, 'notes', 'todo.md'), 'x');
+    await writeFile(join(tempDir, 'notes', '.gitignore'), '*.tmp\n');
+    await trackAdd(['notes/']);
+
+    await trackSwap();
+
+    // .gitignore.sgit-parked exists inside a tracked dir — no guard is active,
+    // but swap mode should suppress the stale-file violation.
+    const shadowResult = await verifyShadow(tempDir);
+    expect(shadowResult.violations).toEqual([]);
+
+    const mainResult = await verifyMain(tempDir);
+    expect(mainResult.violations).toEqual([]);
+  });
+
+  it('detects corrupt state when both .sgit and marker exist', async () => {
+    // Manually create .git.sgit-parked alongside existing .sgit
+    await mkdir(join(tempDir, SWAP_MARKER));
+
+    await expect(assertConsistentState(tempDir)).rejects.toBeInstanceOf(
+      SwapModeCorruptError,
+    );
+  });
+
+  it('disableGitignores/enableGitignores/setupGitignoreGuard refuse while swapped', async () => {
+    await trackSwap();
+
+    expect(() => disableGitignores(tempDir, [])).toThrow(SwapModeActiveError);
+    expect(() => enableGitignores(tempDir, [])).toThrow(SwapModeActiveError);
+    expect(() => setupGitignoreGuard(tempDir, [])).toThrow(
+      SwapModeActiveError,
+    );
+  });
+});