git-drive 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+        id: pnpm-cache
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+  publish-cli:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build CLI
+        run: pnpm build:cli
+
+      - name: Publish to npm
+        working-directory: packages/cli
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,151 @@
+# Architecture
+
+**Analysis Date:** 2026-01-22
+
+## Pattern Overview
+
+**Overall:** Command-line application with modular command pattern and layered abstractions
+
+**Key Characteristics:**
+- CLI entry point dispatching to isolated command handlers
+- Separation of concerns: command logic, git operations, configuration management, error handling
+- Synchronous execution using Node.js child_process for git operations
+- Configuration-driven behavior with persistent state in user home directory
+- Minimal external dependencies (Node.js stdlib only)
+
+## Layers
+
+**CLI Layer (Command Dispatch):**
+- Purpose: Parse command arguments, route to appropriate command handler, manage process lifecycle
+- Location: `src/index.ts`
+- Contains: Main entry point, command registry, usage documentation, error handling wrapper
+- Depends on: All command modules, error handling
+- Used by: Node.js process execution
+
+**Command Layer:**
+- Purpose: Implement high-level workflows for each feature (init, push, archive, restore, list, status)
+- Location: `src/commands/*.ts` (init.ts, push.ts, archive.ts, restore.ts, list.ts, status.ts)
+- Contains: Command-specific business logic, parameter validation, orchestration of lower layers
+- Depends on: Config layer, Git layer, Error types
+- Used by: CLI dispatch layer
+
+**Configuration Layer:**
+- Purpose: Load, save, and validate application configuration (drive path); assert drive connectivity
+- Location: `src/config.ts`
+- Contains: Config file I/O, config validation, drive path helpers
+- Depends on: Node.js fs, path, os modules; Error types
+- Used by: Most command handlers; config validation before operations
+
+**Git Abstraction Layer:**
+- Purpose: Encapsulate git command execution and repository queries with consistent error handling
+- Location: `src/git.ts`
+- Contains: git() execution wrapper, repo root queries, project name resolution, remote URL inspection
+- Depends on: Node.js child_process, path modules
+- Used by: All command handlers that interact with git
+
+**Error Handling Layer:**
+- Purpose: Define custom error types and provide unified error output formatting
+- Location: `src/errors.ts`
+- Contains: GitDriveError exception class, handleError() formatting function
+- Depends on: None
+- Used by: All layers for consistent error propagation and output
+
+## Data Flow
+
+**Push Workflow:**
+
+1. CLI receives `git drive push` command
+2. Index.ts routes to push() handler in `src/commands/push.ts`
+3. push() validates git repository status (isGitRepo)
+4. Loads configuration from ~/.config/git-drive/config.json
+5. Asserts drive is mounted at configured drivePath
+6. Queries project name from git repository root
+7. Creates or updates bare git repository at {drive}/git-drive/{project-name}.git
+8. Adds "drive" remote to local repository pointing to bare repo
+9. Pushes all branches and tags to drive remote
+10. Outputs success message
+
+**Archive Workflow:**
+
+1. CLI receives `git drive archive [--force]` command
+2. archive() in `src/commands/archive.ts` validates git repository
+3. Checks for uncommitted changes (unless --force flag provided)
+4. Calls push() internally to backup all content
+5. Changes working directory to parent
+6. Removes entire local repository directory
+7. Outputs archive confirmation with restore instructions
+
+**Restore Workflow:**
+
+1. CLI receives `git drive restore <project-name> [target-dir]`
+2. restore() in `src/commands/restore.ts` validates configuration
+3. Asserts drive is mounted
+4. Checks that bare repository exists on drive at {drive}/git-drive/{project-name}.git
+5. Clones bare repository to target directory
+6. Renames "origin" remote to "drive" for consistency with push workflow
+7. Outputs success message with restored path
+
+**Status Query Workflow:**
+
+1. CLI receives `git drive status`
+2. status() in `src/commands/status.ts` loads configuration (non-fatal if missing)
+3. Checks drive connectivity by filesystem existence check
+4. If connected: lists all projects in {drive}/git-drive/ by enumerating .git directories
+5. If in a git repository: reports project name and drive remote status
+6. Outputs multi-line status report
+
+**State Management:**
+
+- Configuration state: Persistent JSON file at ~/.config/git-drive/config.json (drivePath property only)
+- Repository state: Stored in git bare repositories on external drive; local repositories maintain standard git state
+- No in-memory state caching; all reads are fresh from filesystem/git
+
+## Key Abstractions
+
+**Git Command Wrapper (git()):**
+- Purpose: Provide safe, consistent git command execution with error propagation
+- Examples: `src/git.ts` functions like git(), getRepoRoot(), getProjectName(), getRemoteUrl()
+- Pattern: execSync with explicit error handling; stdio piping to capture output; optional cwd parameter for working directory context
+
+**GitDriveError Exception:**
+- Purpose: Distinguish application-level errors (user/config issues) from system errors
+- Examples: "No drive configured", "Working tree has uncommitted changes", "Path not found"
+- Pattern: Custom Error subclass with name property; caught and formatted in main error handler
+
+**Configuration Contract:**
+- Purpose: Validate drive path existence and accessibility before operations
+- Examples: requireConfig() (throws if missing), assertDriveMounted() (checks filesystem)
+- Pattern: Fail-fast validation at command start; errors reported immediately to user
+
+**Command Handler Signature:**
+- Purpose: Provide consistent interface for CLI dispatch
+- Pattern: (args: string[]) => void; throws GitDriveError on validation failures; logs results to console
+
+## Entry Points
+
+**CLI Entry Point (Node.js executable):**
+- Location: `src/index.ts` (shebang: #!/usr/bin/env node)
+- Triggers: Installation via npm/git-drive binary; direct node execution
+- Responsibilities: Command parsing, handler dispatch, error handling, process exit code management
+
+**Command Handlers (6 total):**
+- init: Initialize drive path; called once per setup
+- push: Back up current repository; called before archive or periodically
+- archive: Backup and remove local copy; called when archiving projects
+- restore: Retrieve archived project; called to bring archived projects back online
+- list: Display all archived projects; informational query
+- status: Display current drive and repository state; diagnostic command
+
+## Error Handling
+
+**Strategy:** Fail-fast with clear user messaging; distinguish application errors from system errors
+
+**Patterns:**
+- GitDriveError for expected failures (missing config, wrong path, uncommitted changes)
+- Error type checking in main handler: if GitDriveError show message directly, else parse stderr from execSync
+- Process exits with code 1 on any error; code 0 on success
+- All error messages prefixed with "error: " for consistency
+
+---
+
+*Architecture analysis: 2026-01-22*

package/.planning/codebase/CONCERNS.md

@@ -0,0 +1,191 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-01-22
+
+## Tech Debt
+
+**Command Injection Vulnerability via execSync:**
+- Issue: Git arguments are passed directly to `execSync` without sanitization. Paths containing special characters could allow injection.
+- Files: `src/git.ts` (lines 5-9), `src/commands/push.ts` (lines 21, 28, 31, 35-36), `src/commands/archive.ts` (line 16), `src/commands/restore.ts` (line 30, 33)
+- Impact: Malicious project names or file paths could execute arbitrary shell commands
+- Fix approach: Use array form of `execSync` or use `spawn` instead of shell interpolation. Alternatively, escape shell arguments using a library like `shell-escape`.
+
+**Unguarded Process State Mutation in archive:**
+- Issue: `process.chdir("..")` modifies global process state without cleanup or error handling. If removal fails, the process stays in parent directory.
+- Files: `src/commands/archive.ts` (lines 34-35)
+- Impact: If `rmSync` throws after `process.chdir`, the error handler exits from wrong directory, potentially confusing users. Subsequent operations in same process would operate from wrong directory.
+- Fix approach: Wrap in try-finally to restore original cwd. Consider using relative paths or path.join instead of process.chdir.
+
+**Error Information Leakage in Git Operations:**
+- Issue: Git command failures expose full stderr output which might contain sensitive repository or system information.
+- Files: `src/errors.ts` (lines 14-16), `src/git.ts` (lines 4-9)
+- Impact: Sensitive paths, auth tokens, or system details could leak to stdout/stderr
+- Fix approach: Sanitize git error messages, only show relevant error lines, hide sensitive paths.
+
+## Known Bugs
+
+**Race Condition in Push Remote Handling:**
+- Symptoms: If two processes call `push` simultaneously, both might check for existing remote URL and create duplicate remotes
+- Files: `src/commands/push.ts` (lines 26-31)
+- Trigger: Run `git drive push` from two separate terminal windows on same repo simultaneously
+- Workaround: None. User must manually clean up remotes with `git remote rm drive`
+
+**Archive Command Fails Silently on Partial Deletion:**
+- Symptoms: If `rmSync` fails due to file locks (on Windows) or permissions, the output still says "Archived" but local copy remains
+- Files: `src/commands/archive.ts` (lines 34-37)
+- Trigger: On Windows with antivirus scanning files, or with open file handles
+- Workaround: Manually delete directory after error, or use `--force` flag which ignores uncommitted changes but won't prevent rmSync errors
+
+**Restore Creates Clone with Wrong Remote:**
+- Symptoms: Cloning a bare repo creates `origin` remote, then it's renamed to `drive`, but if clone fails midway and user retries, state is inconsistent
+- Files: `src/commands/restore.ts` (lines 30, 33)
+- Trigger: Clone fails (network error, disk full) and user retries
+- Workaround: Manually delete target directory and retry
+
+## Security Considerations
+
+**Config File Permissions Not Set:**
+- Risk: `~/.config/git-drive/config.json` is created world-readable if default umask is permissive. Contains drive path which could be sensitive.
+- Files: `src/config.ts` (lines 20-21)
+- Current mitigation: None
+- Recommendations: Call `chmod 600` on config file after creation. Use `mode` option in `mkdirSync` to set 0o700 permissions.
+
+**No Validation of Path Traversal in Restore:**
+- Risk: User can specify `../../../etc/passwd` as target-dir. While Git clone itself prevents escaping, relative paths could be confusing.
+- Files: `src/commands/restore.ts` (lines 9, 25)
+- Current mitigation: Uses `resolve()` to canonicalize paths
+- Recommendations: Validate target path is within expected directory or is absolute
+
+**Insufficient Argument Validation:**
+- Risk: Commands don't validate argument length or type, leading to confusing errors
+- Files: `src/commands/restore.ts` (line 8), `src/index.ts` (line 32)
+- Current mitigation: Basic checks in some commands
+- Recommendations: Add argument count/type validation before processing
+
+## Performance Bottlenecks
+
+**List Command Iterates All Entries Twice:**
+- Problem: `readdirSync()` called, then filtered, then iterated with `statSync()` for each. No caching or batching.
+- Files: `src/commands/list.ts` (lines 17-33)
+- Cause: Synchronous I/O in loop, no parallelization
+- Improvement path: Use `Dirent.isFile()` option in readdir to avoid extra stat calls. Not a bottleneck for typical drive sizes (<1000 projects) but poor pattern.
+
+**Git Operations Not Buffered:**
+- Problem: Each git command is a separate `execSync` call. `push --all` and `push --tags` execute separately instead of combined.
+- Files: `src/commands/push.ts` (lines 35-36)
+- Cause: Two separate git invocations where one could be chained
+- Improvement path: Combine into single command: `git("push drive --all --tags")`
+
+## Fragile Areas
+
+**Archive Command - Destructive Without Confirmation:**
+- Files: `src/commands/archive.ts`
+- Why fragile: Deletes entire local directory with only a weak check for uncommitted changes. `--force` flag disables even that.
+- Safe modification: Add confirmation prompt before deletion (even with --force). Consider adding `--dry-run` to preview what would be deleted. Add atomic transaction guarantee: push succeeds before any deletion.
+- Test coverage: No tests present. This is the most dangerous command.
+
+**Git Remote Initialization Logic:**
+- Files: `src/commands/push.ts` (lines 19-32)
+- Why fragile: Multiple state branches (remote doesn't exist, exists with same URL, exists with different URL). Easy to miss edge case.
+- Safe modification: Add tests for all three branches. Consider replacing with `git remote set-url --add` if it exists, then prune duplicates.
+- Test coverage: No tests present.
+
+**Config Persistence:**
+- Files: `src/config.ts` (lines 13-21)
+- Why fragile: No atomic writes, no backup of old config. If process crashes during JSON write, config corrupts.
+- Safe modification: Write to temp file first, then rename. Add version field to config format.
+- Test coverage: No tests present.
+
+**Drive Mount Assumption:**
+- Files: `src/config.ts` (line 33), multiple commands
+- Why fragile: Assumes if path exists, drive is mounted. On filesystems with autounmount, path could exist but be stale mount point.
+- Safe modification: Check if path is actually accessible (try to read), not just exists
+- Test coverage: No tests present.
+
+## Scaling Limits
+
+**Bare Repository Storage:**
+- Current capacity: Works fine for ~1000s of projects on typical external drive
+- Limit: No size limits enforced. Bare repos can grow large; no compression or GC recommended to users
+- Scaling path: Document repository GC recommendations. Add `git drive gc` command to run `git gc --aggressive` on all bare repos.
+
+**Synchronous I/O Operations:**
+- Current capacity: All operations block. On drive with 1000+ projects, list/status commands visibly slow
+- Limit: ~100ms per large operation on typical USB drive, scales linearly with project count
+- Scaling path: Switch to async operations for I/O-heavy commands. Parallelize directory operations.
+
+## Dependencies at Risk
+
+**No Production Dependencies:**
+- Risk: Codebase has only dev dependencies (TypeScript, @types/node). Good security posture but limits future extensibility.
+- Impact: Any new feature requiring external library (e.g., progress bars, colors) requires new dep
+- Migration plan: Carefully evaluate any production dependency for security and maintenance status
+
+**execSync from child_process:**
+- Risk: Node's `execSync` doesn't have a maxBuffer safeguard - large git command output (massive commit messages, etc.) could hang or crash process
+- Impact: User loses ability to abort hanging process gracefully
+- Migration plan: Switch to spawn() with streaming output, or add timeout parameter to execSync
+
+## Missing Critical Features
+
+**No Progress Indication:**
+- Problem: Large git push operations give no feedback. User doesn't know if hung or still running.
+- Blocks: Difficult to debug stalled operations
+
+**No Test Suite:**
+- Problem: Zero test coverage. No unit, integration, or e2e tests.
+- Blocks: Refactoring, verification of security fixes, confidence in changes
+
+**No Dry Run Mode:**
+- Problem: Destructive operations (archive, push to wrong remote) have no preview
+- Blocks: Users cannot safely test commands
+
+**No Concurrency Control:**
+- Problem: Multiple processes can push/archive simultaneously, causing corruption
+- Blocks: Safe concurrent usage
+
+**No Recovery from Partial Operations:**
+- Problem: If push succeeds but archive deletion fails, no way to resume or rollback
+- Blocks: Reliable archive operations
+
+## Test Coverage Gaps
+
+**Archive Command - No Tests:**
+- What's not tested: Successful archive flow, archive with uncommitted changes detection, archive with --force flag, rmSync error scenarios, edge case where push succeeds but rm fails
+- Files: `src/commands/archive.ts`
+- Risk: Most destructive operation has zero test coverage. Easy to introduce regressions.
+- Priority: High
+
+**Push Command - No Tests:**
+- What's not tested: Creating bare repo, adding new remote, updating existing remote, concurrent pushes, large repository push
+- Files: `src/commands/push.ts`
+- Risk: Core functionality untested. Remote state bugs undetected.
+- Priority: High
+
+**Restore Command - No Tests:**
+- What's not tested: Successful restore, nonexistent project error, directory exists error, clone failure scenarios
+- Files: `src/commands/restore.ts`
+- Risk: Data recovery untested. Silent failures possible.
+- Priority: High
+
+**Config System - No Tests:**
+- What's not tested: Config loading/saving, corrupted JSON recovery, missing config, permission errors, drive mount detection
+- Files: `src/config.ts`
+- Risk: Configuration system untested. State corruption undetected.
+- Priority: High
+
+**Error Handling - No Tests:**
+- What's not tested: GitDriveError formatting, execSync error parsing, unknown error handling, edge case error messages
+- Files: `src/errors.ts`
+- Risk: Error messages could be unhelpful or expose sensitive info, untested.
+- Priority: Medium
+
+**Index/CLI - No Tests:**
+- What's not tested: Command routing, unknown command handling, help text, missing command handler errors
+- Files: `src/index.ts`
+- Risk: CLI argument parsing untested. Invalid input handling unverified.
+- Priority: Medium
+
+---
+
+*Concerns audit: 2026-01-22*

package/.planning/codebase/CONVENTIONS.md

@@ -0,0 +1,169 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-01-22
+
+## Naming Patterns
+
+**Files:**
+- Kebab-case for command files: `init.ts`, `push.ts`, `archive.ts`, `restore.ts`, `list.ts`, `status.ts`
+- Lowercase for utility modules: `config.ts`, `errors.ts`, `git.ts`, `index.ts`
+- Commands are organized in `src/commands/` directory
+- Extension: `.ts` for all TypeScript files
+
+**Functions:**
+- camelCase for all function names: `init()`, `push()`, `archive()`, `restore()`, `list()`, `status()`
+- Command functions export with pattern: `export function <commandName>(args: string[]): void`
+- Utility functions use camelCase: `loadConfig()`, `saveConfig()`, `getRepoRoot()`, `getProjectName()`, `assertDriveMounted()`
+- Prefix conventions: `is*` for boolean checks (`isGitRepo()`)
+- Prefix conventions: `get*` for retrieval functions (`getRepoRoot()`, `getProjectName()`, `getRemoteUrl()`)
+- Prefix conventions: `require*` for mandatory getters with error throwing (`requireConfig()`)
+- Prefix conventions: `assert*` for validation functions that throw on failure (`assertDriveMounted()`)
+
+**Variables:**
+- camelCase for all variables and parameters: `rawPath`, `drivePath`, `repoRoot`, `projectName`, `storePath`, `bareRepoPath`
+- Constants: UPPER_SNAKE_CASE for configuration paths: `CONFIG_DIR`, `CONFIG_FILE`
+- Private/internal prefixes: None used; all module-level constants are uppercase
+
+**Types:**
+- PascalCase for interfaces: `Config`
+- Record types for object lookups: `Record<string, (args: string[]) => void>` for command handlers
+- Error classes: PascalCase: `GitDriveError`
+
+## Code Style
+
+**Formatting:**
+- Target: ES2022
+- Module system: Node16 with `.js` extensions in imports
+- Strict TypeScript enabled with `strict: true`
+- 2-space indentation (inferred from package and compiled output)
+- Semicolons used consistently at statement ends
+
+**Linting:**
+- No formal linting configuration detected (.eslintrc not present)
+- No Prettier configuration detected (.prettierrc not present)
+- TypeScript compiler with strict mode enforces type safety
+
+**Type Safety:**
+- All function parameters explicitly typed: `args: string[]`, `cwd?: string`, `remoteName: string`
+- Return types explicitly declared: `void`, `string`, `Config`, `boolean`, `Config | null`
+- Optional parameters marked: `cwd?: string`, `targetDir = args[1] || projectName`
+- Union types used for nullable returns: `string | null`
+
+## Import Organization
+
+**Order:**
+1. Node.js built-in modules (`fs`, `path`, `os`, `child_process`)
+2. Relative imports from project modules (`./config.js`, `./errors.js`, `./commands/...`)
+3. No third-party dependencies imported
+
+**Path Aliases:**
+- No path aliases configured; all imports use relative paths
+- Imports include `.js` extension: `import { handleError } from "./errors.js"`
+- Example: `import { init } from "./commands/init.js"`
+
+**Export Pattern:**
+- Named exports used consistently: `export function`, `export class`, `export interface`
+- No default exports
+- Single responsibility per file maintained
+
+## Error Handling
+
+**Patterns:**
+- Custom error class `GitDriveError` extends native `Error` with consistent naming
+- Error instantiation: `throw new GitDriveError("message")`
+- Error handling at top level in `src/index.ts` try-catch block
+- Type-safe error checking: `if (err instanceof GitDriveError)`, `if (err instanceof Error)`
+- Fallback for unknown errors: `else { console.error("An unexpected error occurred.") }`
+- stderr extraction from `execSync` errors: regex match on error message
+- Examples from `src/errors.ts`:
+  ```typescript
+  export function handleError(err: unknown): void {
+    if (err instanceof GitDriveError) {
+      console.error(`error: ${err.message}`);
+    } else if (err instanceof Error) {
+      const msg = err.message;
+      const stderrMatch = msg.match(/stderr:\s*([\s\S]*)/);
+      if (stderrMatch) {
+        console.error(`error: ${stderrMatch[1].trim()}`);
+      } else {
+        console.error(`error: ${msg}`);
+      }
+    } else {
+      console.error("An unexpected error occurred.");
+    }
+  }
+  ```
+
+## Logging
+
+**Framework:** console (built-in)
+
+**Patterns:**
+- `console.log()` for normal output: user messages, status updates
+- `console.error()` for error output: error handling
+- Consistent prefix: `error: ` for error messages
+- Informational output with context: `console.log(\`Drive: ${config.drivePath} (connected)\`)`
+- String interpolation used for variables: `` `Drive configured: ${storePath}` ``
+- Status updates: `console.log(\`Pushed ${projectName} to drive.\`)`
+- Diagnostic output: `console.log(\`Created bare repo: ${bareRepoPath}\`)`
+
+## Comments
+
+**When to Comment:**
+- Used for explaining non-obvious logic or git operations
+- Precedes multi-step operations to clarify intent
+- Examples from codebase:
+  - `// Create bare repo if it doesn't exist`
+  - `// Add or update remote`
+  - `// Push all branches and tags`
+  - `// Check for uncommitted changes`
+  - `// Push first`
+  - `// Remove local copy`
+  - `// execSync errors include stderr in the message`
+  - `// Rename origin to drive so the remote stays consistent`
+
+**JSDoc/TSDoc:**
+- Not used; minimal documentation approach
+- Function purposes clear from names and context
+
+## Function Design
+
+**Size:**
+- Typically 5-40 lines per function
+- Largest file is `src/index.ts` at 51 lines (entry point with usage function)
+- Command implementations: 30-40 lines each
+- Utility functions: 2-10 lines each
+
+**Parameters:**
+- Prefer explicit parameters over implicit state: `function git(args: string, cwd?: string)`
+- Command functions always accept `args: string[]` array from CLI arguments
+- Optional parameters use defaults: `const targetDir = args[1] || projectName`
+
+**Return Values:**
+- Command handlers return `void` and communicate via console.log/error
+- Utility functions return specific types: `string`, `boolean`, `Config`
+- Nullable returns use union types: `string | null`
+- No implicit undefined returns used
+
+## Module Design
+
+**Exports:**
+- Single export per command file: one `export function <command>`
+- Multiple exports in utility modules: `export function loadConfig()`, `export function saveConfig()`, etc.
+- Interface exports for type sharing: `export interface Config`
+- Error class export: `export class GitDriveError`
+
+**Barrel Files:**
+- Not used; imports reference specific files directly
+- Example: `import { init } from "./commands/init.js"` not `import { init } from "./commands/"`
+
+**Module Responsibilities:**
+- `src/config.ts`: Configuration file I/O and drive path utilities
+- `src/git.ts`: Git command execution and git repo inspection
+- `src/errors.ts`: Error class definition and centralized error handling
+- `src/commands/*.ts`: Individual command implementations
+- `src/index.ts`: CLI entry point and command router
+
+---
+
+*Convention analysis: 2026-01-22*

package/.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,94 @@
+# External Integrations
+
+**Analysis Date:** 2026-01-22
+
+## APIs & External Services
+
+**None Detected**
+
+No third-party APIs or external services are used in this codebase.
+
+## Data Storage
+
+**Databases:**
+- Not used - No database integration
+
+**File Storage:**
+- Local filesystem only
+  - Configuration: `~/.config/git-drive/config.json` (user home directory)
+  - Git repositories: External USB drive or mounted filesystem
+  - Client: Built-in Node.js `fs` module (promises-based)
+
+**Caching:**
+- Not used
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Custom - No authentication provider integrated
+- Approach: File-based configuration with implicit trust of drive mount
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- Not used
+
+**Logs:**
+- Console output only
+- Error handling: `console.error()` for errors, `console.log()` for standard output
+- No persistent logging
+
+## CI/CD & Deployment
+
+**Hosting:**
+- npm registry only (published as package)
+- Local development installation
+
+**CI Pipeline:**
+- Not configured - No CI configuration detected
+
+## Environment Configuration
+
+**Required Configuration:**
+- External drive path (configured once via `git drive init <path>`)
+- No environment variables used
+- No `.env` files required
+
+**Configuration Storage:**
+- User configuration: `~/.config/git-drive/config.json`
+- Format: JSON
+- Structure:
+  ```json
+  {
+    "drivePath": "/Volumes/ExternalDrive"
+  }
+  ```
+
+## System Integration
+
+**Git Integration:**
+- Uses `git` command-line tool (via `execSync`)
+- Communicates with Git CLI for repository operations:
+  - `git rev-parse` - Get repository root
+  - `git init --bare` - Create bare repositories
+  - `git remote` - Manage git remotes
+  - `git push` - Push commits to bare repository
+  - `git clone` - Clone from bare repository
+
+**File System Integration:**
+- Direct file system access for:
+  - Drive detection and mounting verification
+  - Repository storage organization
+  - Project metadata (modification times)
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- None
+
+**Outgoing:**
+- None
+
+---
+
+*Integration audit: 2026-01-22*