shadow-git 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "shadow-git",
+  "version": "0.1.0",
+  "description": "A secondary git repository for tracking files excluded from your main repo",
+  "type": "module",
+  "bin": {
+    "sgit": "./dist/cli.js"
+  },
+  "engines": {
+    "node": "^18.19.0 || >=20.6.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "keywords": [
+    "git",
+    "shadow",
+    "sgit",
+    "version-control",
+    "cli"
+  ],
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,55 @@
+import { Command } from 'commander';
+import { findRoot, validateShadowRepo } from './core/repository.js';
+import { forwardToGit } from './commands/forward.js';
+import { registerTrackCommands } from './commands/track/index.js';
+import { SgitError } from './core/errors.js';
+import * as logger from './utils/logger.js';
+
+async function run(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (
+    args.length === 0 ||
+    args[0] === 'track' ||
+    args[0].startsWith('-')
+  ) {
+    const program = new Command('sgit')
+      .description('Shadow Git — a secondary git repository for your project')
+      .version('0.1.0');
+
+    registerTrackCommands(program);
+
+    program.addHelpText(
+      'after',
+      `
+Track commands:
+  sgit track init          Initialize shadow repository
+  sgit track add           Start shadow-tracking paths (--adopt to move from main git)
+  sgit track remove        Stop shadow-tracking paths
+  sgit track list          List all shadow-tracked paths
+  sgit track sync          Regenerate exclude files
+  sgit track verify        Validate staged files
+  sgit track destroy       Remove shadow repository
+  sgit track completion    Install shell completions
+
+All other commands are forwarded to git in the shadow repository:
+  sgit status, sgit commit, sgit log, sgit diff, ...`,
+    );
+
+    await program.parseAsync(process.argv);
+  } else {
+    const root = await findRoot();
+    await validateShadowRepo(root);
+    const exitCode = forwardToGit(root, args);
+    process.exit(exitCode);
+  }
+}
+
+run().catch((err) => {
+  if (err instanceof SgitError) {
+    logger.error(err.message);
+  } else {
+    console.error(err);
+  }
+  process.exit(1);
+});

package/src/commands/forward.ts

@@ -0,0 +1,12 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+export function forwardToGit(root: string, args: string[]): number {
+  const sgitDir = join(root, '.sgit');
+  const result = spawnSync(
+    'git',
+    [`--git-dir=${sgitDir}`, `--work-tree=${root}`, ...args],
+    { stdio: 'inherit' },
+  );
+  return result.status ?? 1;
+}

package/src/commands/track/add.ts

@@ -0,0 +1,91 @@
+import { join } from 'node:path';
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { findRoot, validateShadowRepo } from '../../core/repository.js';
+import { execGit } from '../../core/git.js';
+import { normalizePath } from '../../core/paths.js';
+import { addPath, readManifest } from '../../core/manifest.js';
+import { syncExcludes } from './sync.js';
+import {
+  PathNotFoundError,
+  PathTrackedByMainError,
+} from '../../core/errors.js';
+import * as logger from '../../utils/logger.js';
+
+export async function trackAdd(paths: string[], opts: { adopt?: boolean } = {}): Promise<void> {
+  const root = await findRoot();
+  await validateShadowRepo(root);
+  const sgitDir = join(root, '.sgit');
+
+  const added: string[] = [];
+
+  for (const inputPath of paths) {
+    const normalized = await normalizePath(inputPath, root);
+
+    // Must exist on disk
+    const checkPath = normalized.endsWith('/')
+      ? normalized.slice(0, -1)
+      : normalized;
+    try {
+      await access(join(root, checkPath), constants.F_OK);
+    } catch {
+      throw new PathNotFoundError(normalized);
+    }
+
+    // Check if already tracked by sgit (skip adopt if so)
+    const manifest = await readManifest(root);
+    const alreadyTracked = manifest.paths.includes(normalized);
+
+    // Must not be tracked by main git (unless --adopt)
+    let trackedByMain = false;
+    try {
+      await execGit(['ls-files', '--error-unmatch', checkPath], {
+        gitDir: join(root, '.git'),
+        workTree: root,
+      });
+      trackedByMain = true;
+    } catch {
+      // git error = not tracked by main
+    }
+
+    if (trackedByMain) {
+      if (opts.adopt && !alreadyTracked) {
+        const rmArgs = normalized.endsWith('/')
+          ? ['rm', '--cached', '-r', checkPath]
+          : ['rm', '--cached', checkPath];
+        await execGit(rmArgs, { gitDir: join(root, '.git'), workTree: root });
+      } else if (!opts.adopt) {
+        throw new PathTrackedByMainError(normalized);
+      }
+      // If adopt + alreadyTracked, skip git rm — already in sgit
+    }
+
+    // Add to manifest
+    const wasAdded = await addPath(root, normalized);
+    if (wasAdded) {
+      added.push(normalized);
+    }
+  }
+
+  // Sync exclude files
+  await syncExcludes(root);
+
+  // Force-add to shadow repo
+  for (const p of added) {
+    const gitPath = p.endsWith('/') ? p.slice(0, -1) : p;
+    await execGit(['add', '-f', gitPath], {
+      gitDir: sgitDir,
+      workTree: root,
+    });
+  }
+
+  // Print summary
+  if (added.length > 0) {
+    logger.success(`Tracking ${added.length} new path(s):`);
+    for (const p of added) {
+      logger.info(`  ${p}`);
+    }
+  } else {
+    logger.info('All paths already tracked.');
+  }
+}

package/src/commands/track/completion.ts

@@ -0,0 +1,243 @@
+import { join, dirname } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import * as logger from '../../utils/logger.js';
+
+function bashCompletion(): string {
+  return `# sgit bash completion
+_sgit() {
+  local cur prev words cword
+  _init_completion || return
+
+  if [[ \${words[1]} == "track" ]]; then
+    if [[ $cword -eq 2 ]]; then
+      COMPREPLY=($(compgen -W "init add remove list sync verify destroy completion" -- "$cur"))
+      return
+    fi
+
+    local subcmd="\${words[2]}"
+    case "$subcmd" in
+      add)
+        if [[ $cur == -* ]]; then
+          COMPREPLY=($(compgen -W "--adopt" -- "$cur"))
+        else
+          _filedir
+        fi
+        ;;
+      remove)
+        local paths
+        paths=$(sgit track list 2>/dev/null)
+        COMPREPLY=($(compgen -W "$paths" -- "$cur"))
+        ;;
+      verify)
+        COMPREPLY=($(compgen -W "--main --shadow" -- "$cur"))
+        ;;
+      destroy)
+        COMPREPLY=($(compgen -W "--force" -- "$cur"))
+        ;;
+      completion)
+        if [[ $prev == "--shell" ]]; then
+          COMPREPLY=($(compgen -W "bash zsh fish" -- "$cur"))
+        elif [[ $cur == -* ]]; then
+          COMPREPLY=($(compgen -W "--shell" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "install" -- "$cur"))
+        fi
+        ;;
+    esac
+    return
+  fi
+
+  if [[ $cword -eq 1 ]]; then
+    # "track" plus all git subcommands
+    local git_cmds
+    git_cmds=$(git --list-cmds=main,others 2>/dev/null)
+    COMPREPLY=($(compgen -W "track $git_cmds" -- "$cur"))
+    return
+  fi
+
+  # Non-track commands: delegate to git completion
+  if declare -f __git_wrap__git_main &>/dev/null; then
+    __git_wrap__git_main
+  elif declare -f _git &>/dev/null; then
+    _git
+  fi
+}
+complete -F _sgit sgit
+`;
+}
+
+function zshCompletion(): string {
+  return `#compdef sgit
+# sgit zsh completion
+
+_sgit_track() {
+  local -a subcmds
+  subcmds=(
+    'init:Initialize shadow repository'
+    'add:Start shadow-tracking paths'
+    'remove:Stop shadow-tracking paths'
+    'list:List all shadow-tracked paths'
+    'sync:Regenerate exclude files'
+    'verify:Validate staged files'
+    'destroy:Remove shadow repository'
+    'completion:Install shell completions'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'track subcommand' subcmds
+    return
+  fi
+
+  case "\${words[2]}" in
+    add)
+      _arguments '--adopt[Move main-git-tracked files to shadow tracking]' '*:file:_files'
+      ;;
+    remove)
+      local -a paths
+      paths=(\${(f)"$(sgit track list 2>/dev/null)"})
+      _describe 'tracked path' paths
+      ;;
+    verify)
+      _arguments '--main[Check main repo]' '--shadow[Check shadow repo]'
+      ;;
+    destroy)
+      _arguments '--force[Skip confirmation]'
+      ;;
+    completion)
+      _arguments '--shell[Shell type]:shell:(bash zsh fish)' '1:action:(install)'
+      ;;
+  esac
+}
+
+_sgit() {
+  if (( CURRENT == 2 )); then
+    local -a track_cmd
+    track_cmd=('track:Manage shadow-tracked paths')
+    _describe 'sgit command' track_cmd
+    # Also offer all git subcommands
+    words[1]=git
+    _git
+    return
+  fi
+
+  case "\${words[2]}" in
+    track)
+      (( CURRENT-- ))
+      shift words
+      _sgit_track
+      ;;
+    *)
+      words[1]=git
+      _git
+      ;;
+  esac
+}
+
+_sgit "$@"
+`;
+}
+
+function fishCompletion(): string {
+  return `# sgit fish completion
+
+# Inherit all git completions (sgit forwards non-track commands to git)
+complete -c sgit -w git
+
+# Add "track" as a top-level subcommand
+complete -c sgit -n '__fish_use_subcommand' -a track -d 'Manage shadow-tracked paths'
+
+# Track subcommands
+complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a init -d 'Initialize shadow repository'
+complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a add -d 'Start shadow-tracking paths'
+complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a remove -d 'Stop shadow-tracking paths'
+complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a list -d 'List all shadow-tracked paths'
+complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a sync -d 'Regenerate exclude files'
+complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a verify -d 'Validate staged files'
+complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a destroy -d 'Remove shadow repository'
+complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a completion -d 'Install shell completions'
+
+# Track add options and file completions
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from add' -l adopt -d 'Move main-git-tracked files'
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from add' -F
+
+# Track remove — complete from manifest
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from remove' -a '(sgit track list 2>/dev/null)'
+
+# Track verify options
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from verify' -l main -d 'Check main repo'
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from verify' -l shadow -d 'Check shadow repo'
+
+# Track destroy options
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from destroy' -l force -d 'Skip confirmation'
+
+# Track completion options
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from completion' -a install -d 'Install completions'
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from completion' -l shell -d 'Shell type' -ra 'bash zsh fish'
+`;
+}
+
+function detectShell(): string {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) return 'zsh';
+  if (shell.includes('fish')) return 'fish';
+  return 'bash';
+}
+
+function getScript(shell: string): string {
+  switch (shell) {
+    case 'zsh':
+      return zshCompletion();
+    case 'fish':
+      return fishCompletion();
+    default:
+      return bashCompletion();
+  }
+}
+
+function getInstallPath(shell: string): string {
+  const home = homedir();
+  switch (shell) {
+    case 'zsh':
+      return join(home, '.zsh', 'completions', '_sgit');
+    case 'fish':
+      return join(home, '.config', 'fish', 'completions', 'sgit.fish');
+    default:
+      return join(home, '.local', 'share', 'bash-completion', 'completions', 'sgit');
+  }
+}
+
+export async function trackCompletion(
+  action?: string,
+  opts?: { shell?: string },
+): Promise<void> {
+  const shell = opts?.shell || detectShell();
+  const script = getScript(shell);
+
+  if (!action) {
+    process.stdout.write(script);
+    return;
+  }
+
+  if (action === 'install') {
+    const installPath = getInstallPath(shell);
+    await mkdir(dirname(installPath), { recursive: true });
+    await writeFile(installPath, script, { mode: 0o644 });
+    logger.success(`Installed ${shell} completions to ${installPath}`);
+
+    if (shell === 'zsh') {
+      logger.info(
+        'Ensure ~/.zsh/completions is in your $fpath. Add to ~/.zshrc:\n' +
+          '  fpath=(~/.zsh/completions $fpath)\n' +
+          '  autoload -Uz compinit && compinit',
+      );
+    }
+    return;
+  }
+
+  logger.error(`Unknown action: ${action}. Use 'install' or omit for stdout.`);
+  process.exit(1);
+}
+
+// Exported for testing
+export { bashCompletion, zshCompletion, fishCompletion, detectShell, getInstallPath };

package/src/commands/track/destroy.ts

@@ -0,0 +1,81 @@
+import { join } from 'node:path';
+import { readFile, writeFile, rm } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { findRoot, validateShadowRepo } from '../../core/repository.js';
+import { uninstallMainHook } from '../../core/hooks.js';
+import { SGIT_MARKER, SGIT_MANAGED_HEADER } from '../../core/exclude.js';
+import * as logger from '../../utils/logger.js';
+
+export async function trackDestroy(opts: {
+  force?: boolean;
+}): Promise<void> {
+  const root = await findRoot();
+  await validateShadowRepo(root);
+
+  if (!opts.force) {
+    const confirmed = await confirm(
+      'This will permanently remove the shadow repository. Continue?',
+    );
+    if (!confirmed) {
+      logger.info('Aborted.');
+      return;
+    }
+  }
+
+  // Remove sgit entries from .git/info/exclude
+  const excludePath = join(root, '.git', 'info', 'exclude');
+  try {
+    const content = await readFile(excludePath, 'utf-8');
+    const lines = content.split('\n');
+    const result: string[] = [];
+    let skipNext = false;
+    for (const line of lines) {
+      if (line === SGIT_MANAGED_HEADER) {
+        skipNext = false;
+        continue;
+      }
+      if (line === SGIT_MARKER) {
+        skipNext = true;
+        continue;
+      }
+      // Strip legacy inline-comment format: "entry # sgit"
+      if (line.endsWith(` ${SGIT_MARKER}`)) {
+        continue;
+      }
+      if (skipNext) {
+        skipNext = false;
+        continue;
+      }
+      result.push(line);
+    }
+    const cleaned = result.join('\n');
+    // Trim trailing blank lines
+    await writeFile(excludePath, cleaned.replace(/\n+$/, '\n'));
+  } catch {
+    // Exclude file might not exist
+  }
+
+  // Uninstall main repo hook
+  await uninstallMainHook(root);
+
+  // Delete .sgit/
+  await rm(join(root, '.sgit'), { recursive: true, force: true });
+
+  // Delete .sgit.json
+  await rm(join(root, '.sgit.json'), { force: true });
+
+  logger.success('Shadow repository removed.');
+}
+
+async function confirm(message: string): Promise<boolean> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(`${message} [y/N] `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y');
+    });
+  });
+}

package/src/commands/track/index.ts

@@ -0,0 +1,91 @@
+import { Command } from 'commander';
+import { SgitError } from '../../core/errors.js';
+import * as logger from '../../utils/logger.js';
+import { trackInit } from './init.js';
+import { trackSync } from './sync.js';
+import { trackAdd } from './add.js';
+import { trackRemove } from './remove.js';
+import { trackList } from './list.js';
+import { trackVerify } from './verify.js';
+import { trackDestroy } from './destroy.js';
+import { trackCompletion } from './completion.js';
+
+export function registerTrackCommands(program: Command): void {
+  const track = program
+    .command('track')
+    .description('Manage shadow-tracked paths');
+
+  track
+    .command('init')
+    .description('Initialize shadow repository')
+    .action(wrapAction(trackInit));
+
+  track
+    .command('add')
+    .description('Start shadow-tracking paths')
+    .argument('<paths...>')
+    .option('--adopt', 'Move main-git-tracked files to shadow tracking')
+    .action(wrapAction(async (paths: string[], opts: { adopt?: boolean }) => trackAdd(paths, opts)));
+
+  track
+    .command('remove')
+    .description('Stop shadow-tracking paths')
+    .argument('<paths...>')
+    .action(wrapAction(async (paths: string[]) => trackRemove(paths)));
+
+  track
+    .command('list')
+    .description('List all shadow-tracked paths')
+    .action(wrapAction(async () => { await trackList(); }));
+
+  track
+    .command('sync')
+    .description('Regenerate exclude files from .sgit.json')
+    .action(wrapAction(trackSync));
+
+  track
+    .command('verify')
+    .description('Validate staged files against manifest')
+    .option('--main', 'Check main repo staged files')
+    .option('--shadow', 'Check shadow repo staged files')
+    .action(
+      wrapAction(async (opts: { main?: boolean; shadow?: boolean }) =>
+        trackVerify(opts),
+      ),
+    );
+
+  track
+    .command('destroy')
+    .description('Remove shadow repository entirely')
+    .option('--force', 'Skip confirmation prompt')
+    .action(
+      wrapAction(async (opts: { force?: boolean }) => trackDestroy(opts)),
+    );
+
+  track
+    .command('completion')
+    .description('Install shell completion scripts')
+    .argument('[action]', 'Action (install)')
+    .option('--shell <name>', 'Shell (bash, zsh, fish)')
+    .action(
+      wrapAction(async (action?: string, opts?: { shell?: string }) =>
+        trackCompletion(action, opts),
+      ),
+    );
+}
+
+export function wrapAction(
+  fn: (...args: any[]) => Promise<void>,
+): (...args: any[]) => Promise<void> {
+  return async (...args: any[]) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      if (err instanceof SgitError) {
+        logger.error(err.message);
+        process.exit(1);
+      }
+      throw err;
+    }
+  };
+}