shadow-git 1.0.3 → 1.1.0

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/utils/logger.ts

@@ -19,3 +19,15 @@ 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`);
+}

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,
+    );
+  });
+});

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

@@ -46,25 +46,25 @@ describe('track verify', () => {
       expect(result.valid).toBe(true);
     });
 
-    it('blocks stale .gitignore-sgit.bat when no guard is active', async () => {
+    it('blocks stale .gitignore.sgit-parked when no guard is active', async () => {
       await mkdir(join(tempDir, 'docs'), { recursive: true });
       await writeFile(join(tempDir, 'docs', 'file.md'), 'content');
       await trackAdd(['docs']);
 
-      // Create a stale .gitignore-sgit.bat
+      // Create a stale .gitignore.sgit-parked
       await writeFile(
-        join(tempDir, 'docs', '.gitignore-sgit.bat'),
+        join(tempDir, 'docs', '.gitignore.sgit-parked'),
         'stale\n',
       );
 
       const result = await verifyMain(tempDir);
       expect(result.valid).toBe(false);
       expect(
-        result.violations.some((v) => v.includes('.gitignore-sgit.bat')),
+        result.violations.some((v) => v.includes('.gitignore.sgit-parked')),
       ).toBe(true);
     });
 
-    it('skips stale .gitignore-sgit.bat check when guard is active', async () => {
+    it('skips stale .gitignore.sgit-parked check when guard is active', async () => {
       await mkdir(join(tempDir, 'docs'), { recursive: true });
       await writeFile(join(tempDir, 'docs', 'file.md'), 'content');
       await trackAdd(['docs']);
@@ -74,13 +74,13 @@ describe('track verify', () => {
         String(process.pid),
       );
       await writeFile(
-        join(tempDir, 'docs', '.gitignore-sgit.bat'),
+        join(tempDir, 'docs', '.gitignore.sgit-parked'),
         'managed by guard\n',
       );
 
       const result = await verifyMain(tempDir);
       expect(
-        result.violations.some((v) => v.includes('.gitignore-sgit.bat')),
+        result.violations.some((v) => v.includes('.gitignore.sgit-parked')),
       ).toBe(false);
 
       unlinkSync(join(tempDir, '.sgit', '.gitignore-guard'));
@@ -147,43 +147,43 @@ describe('track verify', () => {
       expect(result.violations.some((v) => v.includes('.sgit.json') && v.includes('cannot delete'))).toBe(true);
     });
 
-    it('blocks stale .gitignore-sgit.bat when no guard is active', async () => {
+    it('blocks stale .gitignore.sgit-parked when no guard is active', async () => {
       await mkdir(join(tempDir, 'docs'), { recursive: true });
       await writeFile(join(tempDir, 'docs', 'file.md'), 'content');
       await trackAdd(['docs']);
 
-      // Create a stale .gitignore-sgit.bat
+      // Create a stale .gitignore.sgit-parked
       await writeFile(
-        join(tempDir, 'docs', '.gitignore-sgit.bat'),
+        join(tempDir, 'docs', '.gitignore.sgit-parked'),
         'stale\n',
       );
 
       const result = await verifyShadow(tempDir);
       expect(result.valid).toBe(false);
       expect(
-        result.violations.some((v) => v.includes('.gitignore-sgit.bat')),
+        result.violations.some((v) => v.includes('.gitignore.sgit-parked')),
       ).toBe(true);
     });
 
-    it('skips stale .gitignore-sgit.bat check when guard is active', async () => {
+    it('skips stale .gitignore.sgit-parked check when guard is active', async () => {
       await mkdir(join(tempDir, 'docs'), { recursive: true });
       await writeFile(join(tempDir, 'docs', 'file.md'), 'content');
       await trackAdd(['docs']);
 
-      // Simulate active guard: create lock with current PID + stale .bat
+      // Simulate active guard: create lock with current PID + stale .gitignore.sgit-parked
       writeFileSync(
         join(tempDir, '.sgit', '.gitignore-guard'),
         String(process.pid),
       );
       await writeFile(
-        join(tempDir, 'docs', '.gitignore-sgit.bat'),
+        join(tempDir, 'docs', '.gitignore.sgit-parked'),
         'managed by guard\n',
       );
 
       const result = await verifyShadow(tempDir);
-      // Should not report .bat files as violations when guard is active
+      // Should not report stale files as violations when guard is active
       expect(
-        result.violations.some((v) => v.includes('.gitignore-sgit.bat')),
+        result.violations.some((v) => v.includes('.gitignore.sgit-parked')),
       ).toBe(false);
 
       // Cleanup

package/tests/core/exclude.test.ts

@@ -50,17 +50,17 @@ describe('generateMainExclude', () => {
     expect(result).toContain('notes/todo.md\n');
   });
 
-  it('includes .gitignore-sgit.bat in managed block', () => {
+  it('includes .gitignore.sgit-parked in managed block', () => {
     const result = generateMainExclude('', ['notes.md']);
-    expect(result).toContain('.gitignore-sgit.bat\n');
+    expect(result).toContain('.gitignore.sgit-parked\n');
   });
 
-  it('orders entries: .sgit, .sgit.json, .gitignore-sgit.bat, then manifest paths', () => {
+  it('orders entries: .sgit, .sgit.json, .gitignore.sgit-parked, then manifest paths', () => {
     const result = generateMainExclude('', ['z.txt', 'a.txt']);
     const lines = result.split('\n');
     const sgitLine = lines.indexOf('.sgit');
     const sgitJsonLine = lines.indexOf('.sgit.json');
-    const batLine = lines.indexOf('.gitignore-sgit.bat');
+    const batLine = lines.indexOf('.gitignore.sgit-parked');
     const zLine = lines.indexOf('z.txt');
     const aLine = lines.indexOf('a.txt');
     expect(sgitLine).toBeLessThan(sgitJsonLine);
@@ -158,19 +158,19 @@ describe('generateShadowExclude', () => {
     expect(lines).not.toContain('!./');
   });
 
-  it('re-ignores .gitignore-sgit.bat after allow-list', () => {
+  it('re-ignores .gitignore.sgit-parked after allow-list', () => {
     const result = generateShadowExclude(['docs/']);
     const lines = result.split('\n');
     const allowLine = lines.indexOf('!docs/**');
-    const batLine = lines.indexOf('.gitignore-sgit.bat');
+    const batLine = lines.indexOf('.gitignore.sgit-parked');
     expect(batLine).toBeGreaterThan(-1);
     expect(batLine).toBeGreaterThan(allowLine);
   });
 
-  it('includes .gitignore-sgit.bat even for empty manifest', () => {
+  it('includes .gitignore.sgit-parked even for empty manifest', () => {
     const result = generateShadowExclude([]);
     const lines = result.split('\n');
-    expect(lines).toContain('.gitignore-sgit.bat');
+    expect(lines).toContain('.gitignore.sgit-parked');
   });
 
   it('has no per-path comment lines', () => {
@@ -186,12 +186,12 @@ describe('generateShadowExclude', () => {
     expect(lines).toContain('temp2/cache/');
   });
 
-  it('places ignore rules after un-ignore and before .gitignore-sgit.bat', () => {
+  it('places ignore rules after un-ignore and before .gitignore.sgit-parked', () => {
     const result = generateShadowExclude(['docs/'], ['docs/cache/']);
     const lines = result.split('\n');
     const unignoreLine = lines.indexOf('!docs/**');
     const ignoreLine = lines.indexOf('docs/cache/');
-    const batLine = lines.indexOf('.gitignore-sgit.bat');
+    const batLine = lines.indexOf('.gitignore.sgit-parked');
     expect(ignoreLine).toBeGreaterThan(unignoreLine);
     expect(ignoreLine).toBeLessThan(batLine);
   });