git-drive 0.1.0

package/.planning/codebase/STACK.md

@@ -0,0 +1,77 @@
+# Technology Stack
+
+**Analysis Date:** 2026-01-22
+
+## Languages
+
+**Primary:**
+- TypeScript 5.9.3 - All source code
+
+**Runtime:**
+- Node.js 14.17+ (from TypeScript compiler requirement)
+
+## Runtime
+
+**Environment:**
+- Node.js (ES2022 target)
+
+**Package Manager:**
+- npm - Lockfile: `package-lock.json` (present)
+
+## Frameworks
+
+**Core:**
+- None - Native Node.js modules only
+- Uses built-in modules: `child_process`, `fs`, `path`, `os`
+
+**Build/Dev:**
+- TypeScript 5.9.3 - Compilation from `src/` to `dist/`
+- Module system: Node16 ESM
+
+## Key Dependencies
+
+**Development Only:**
+- `typescript` 5.9.3 - TypeScript compiler
+- `@types/node` 22.19.7 - Type definitions for Node.js built-in modules
+
+**Runtime Dependencies:**
+- None - Zero runtime dependencies
+
+## Configuration
+
+**Environment:**
+- Configuration directory: `~/.config/git-drive/config.json`
+- Stores single configuration: `drivePath` (external drive path)
+- Configuration persisted as JSON
+
+**Build:**
+- TypeScript compiler config: `tsconfig.json`
+- Target: ES2022
+- Module resolution: Node16 (ESM)
+- Output: `./dist` directory
+- Input: `./src` directory
+
+## Compiler Options
+
+**Settings:**
+- `strict: true` - Strict type checking enabled
+- `esModuleInterop: true` - CommonJS compatibility for imports
+- `declaration: false` - No `.d.ts` generation
+- `sourceMap: false` - No source maps
+- `moduleResolution: Node16` - Node.js ESM module resolution
+
+## Project Metadata
+
+**Type:** Command-line tool (bin entry point)
+
+**Entry Point:**
+- Executable: `dist/index.js`
+- Command: `git-drive` (registered via package.json bin)
+
+**Build Scripts:**
+- `npm run build` - Compile TypeScript to `dist/`
+- `npm run dev` - Watch mode compilation
+
+---
+
+*Stack analysis: 2026-01-22*

package/.planning/codebase/STRUCTURE.md

@@ -0,0 +1,157 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-01-22
+
+## Directory Layout
+
+```
+git-drive/
+├── src/                    # TypeScript source code
+│   ├── commands/           # Command handlers (6 modules)
+│   │   ├── init.ts
+│   │   ├── push.ts
+│   │   ├── archive.ts
+│   │   ├── restore.ts
+│   │   ├── list.ts
+│   │   └── status.ts
+│   ├── index.ts            # CLI entry point with command dispatch
+│   ├── config.ts           # Configuration management
+│   ├── git.ts              # Git command abstraction layer
+│   └── errors.ts           # Error types and formatting
+├── dist/                   # Compiled JavaScript (generated)
+│   └── commands/
+├── .planning/              # Planning documents (generated)
+│   └── codebase/
+├── package.json            # npm configuration and dependencies
+├── tsconfig.json           # TypeScript compiler options
+└── .gitignore              # Git ignore patterns
+```
+
+## Directory Purposes
+
+**src/ (Source Code):**
+- Purpose: All TypeScript source files for the application
+- Contains: Entry point, command implementations, utilities, error definitions
+- Key files: `index.ts` (entry), `commands/` (all command logic)
+
+**src/commands/ (Command Implementations):**
+- Purpose: Individual command handler modules, each implementing one CLI command
+- Contains: init, push, archive, restore, list, status command logic
+- Key files: Each file exports a function matching (args: string[]) => void signature
+
+**dist/ (Compiled Output):**
+- Purpose: Generated JavaScript output from TypeScript compilation
+- Contains: Transpiled .js files mirroring src/ structure
+- Generated: Yes
+- Committed: No (in .gitignore)
+
+**.planning/codebase/ (Analysis Documents):**
+- Purpose: GSD codebase documentation for code generation planning
+- Contains: ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md (when written)
+- Generated: Yes (by orchestrator)
+- Committed: Yes (version controlled for reference)
+
+## Key File Locations
+
+**Entry Points:**
+- `src/index.ts`: Main CLI entry point; shebang executable; imports all commands and dispatches by name
+
+**Configuration:**
+- `src/config.ts`: Config loading/saving; configuration file location: ~/.config/git-drive/config.json
+- `tsconfig.json`: TypeScript compilation target ES2022, Node16 modules, strict mode enabled
+
+**Core Logic:**
+- `src/git.ts`: git command wrapper; Repository queries (root, project name, remotes)
+- `src/errors.ts`: GitDriveError type; handleError() formatter for console output
+- `src/commands/*.ts`: Six command modules; each handles one CLI operation
+
+**Testing:**
+- Not applicable (no test files present)
+
+## Naming Conventions
+
+**Files:**
+- `camelCase.ts` for source files: index.ts, config.ts, git.ts, errors.ts
+- Command files match command names: init.ts, push.ts, archive.ts, restore.ts, list.ts, status.ts
+- Compiled output: `camelCase.js` in dist/ directory
+
+**Directories:**
+- `lowercase/` for directory names: src, dist, commands, .planning
+- Domain-specific grouping: commands/ contains all CLI command handlers
+
+**Functions:**
+- camelCase for all functions: init(), push(), archive(), restore(), list(), status(), git(), loadConfig(), saveConfig(), etc.
+- Handler functions export command function: export function {command}(args: string[])
+- Utility functions use descriptive names: getRepoRoot(), getProjectName(), getDriveStorePath(), assertDriveMounted()
+
+**Types/Interfaces:**
+- PascalCase for types: GitDriveError, Config
+- Config interface has required properties in camelCase: drivePath
+
+**Variables:**
+- camelCase for all variables and parameters: args, config, drivePath, projectName, storePath, bareRepoPath, etc.
+
+## Where to Add New Code
+
+**New Command:**
+1. Create new file in `src/commands/{command-name}.ts`
+2. Export function matching signature: `export function {command-name}(args: string[]): void`
+3. Import in `src/index.ts` at top: `import { {command-name} } from "./commands/{command-name}.js"`
+4. Add to commands record: `{command-name},` in commands object
+5. Add help text to printUsage() function
+6. Implementation pattern: validate args → load config → assert prerequisites → perform operation → console.log() result
+
+**New Utility Module:**
+1. Create file at `src/{utility-name}.ts` (e.g., src/cache.ts, src/validate.ts)
+2. Export functions with clear names
+3. Import in commands that need them
+4. Follow error handling pattern: throw GitDriveError for application errors
+
+**Config Changes:**
+1. Update Config interface in `src/config.ts` (add new property)
+2. Update loadConfig() and saveConfig() JSON serialization (happens automatically)
+3. Update requireConfig() validation if new field is required
+4. Update all dependent code to access new property
+
+**Git Operations:**
+1. Add new helper function in `src/git.ts`
+2. Follow pattern: use git() wrapper, return trimmed output or null on error
+3. Add try-catch for git() calls that might fail gracefully
+4. Import and use in commands
+
+**Error Handling:**
+1. Throw GitDriveError with descriptive message for user-facing errors
+2. Let system errors propagate; main handler extracts stderr from execSync
+3. Messages should be actionable: "... Run: git drive init <path>"
+
+## Special Directories
+
+**dist/ (Build Output):**
+- Purpose: Generated JavaScript from TypeScript compilation via `npm run build`
+- Generated: Yes
+- Committed: No
+
+**.planning/codebase/ (Documentation):**
+- Purpose: Store GSD analysis documents for code generation planning
+- Generated: Yes (orchestrator writes these)
+- Committed: Yes (version controlled)
+
+**.claude/ (Context Storage):**
+- Purpose: Agent context and state (auto-generated by Claude agent)
+- Generated: Yes
+- Committed: No
+
+## Import Patterns
+
+**External Modules:**
+- Node.js built-ins only: fs, child_process, path, os
+- No npm dependencies (dev-only: typescript, @types/node)
+
+**Internal Imports:**
+- Use .js extensions in import statements (for ES Module compatibility): `import { init } from "./commands/init.js"`
+- Relative imports: `../config.js`, `../errors.js`, `../git.js`
+- Path aliases: Not used; relative imports preferred
+
+---
+
+*Structure analysis: 2026-01-22*

package/.planning/codebase/TESTING.md

@@ -0,0 +1,156 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-01-22
+
+## Test Framework
+
+**Runner:**
+- Not detected
+- No testing framework configured (no jest.config.*, vitest.config.*, package.json test script)
+
+**Assertion Library:**
+- Not applicable - no tests present
+
+**Run Commands:**
+- No test commands defined in `package.json`
+- Current package.json scripts:
+  ```json
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+  ```
+
+## Test File Organization
+
+**Location:**
+- No test files detected in codebase
+- No `__tests__` directory
+- No `.test.ts` or `.spec.ts` files
+
+**Naming:**
+- No test naming convention established
+
+**Structure:**
+- Not applicable - no tests present
+
+## Test Structure
+
+**Suite Organization:**
+- Not applicable - no tests present
+
+**Patterns:**
+- Not applicable - no tests present
+
+## Mocking
+
+**Framework:**
+- Not detected - no mocking library configured
+
+**Patterns:**
+- Not applicable - no mocks present
+
+**What to Mock:**
+- If tests were to be added, candidates for mocking:
+  - File system operations (`fs` module): `readFileSync`, `writeFileSync`, `mkdirSync`, `existsSync`, `readdirSync`, `statSync`, `rmSync`
+  - Child process execution (`child_process.execSync`): Would need mocking to avoid running real git commands
+  - Environment paths: `homedir()`, `process.argv`, `process.cwd()`, `process.chdir()`
+
+**What NOT to Mock:**
+- If tests were to be added, avoid mocking:
+  - Error classes (`GitDriveError`) - should use real instances
+  - Type interfaces (`Config`) - used for type checking only
+  - Custom utility functions - better to test with real implementations
+
+## Fixtures and Factories
+
+**Test Data:**
+- Not applicable - no test fixtures present
+
+**Location:**
+- If needed, should be created in: `src/__fixtures__/` or `src/__testdata__/`
+
+## Coverage
+
+**Requirements:**
+- No coverage requirements enforced
+- No coverage configuration present
+
+**View Coverage:**
+- Not applicable - no test runner configured
+
+## Test Types
+
+**Unit Tests:**
+- Not present
+- Candidates for unit testing:
+  - `src/config.ts` functions: `loadConfig()`, `saveConfig()`, `requireConfig()`, `assertDriveMounted()`, `getDriveStorePath()`
+  - `src/git.ts` functions: `git()`, `getRepoRoot()`, `getProjectName()`, `getRemoteUrl()`, `isGitRepo()`
+  - `src/errors.ts`: `GitDriveError` class and `handleError()` function
+
+**Integration Tests:**
+- Not present
+- Candidates for integration testing:
+  - `src/commands/init.ts`: Configuration setup and drive initialization
+  - `src/commands/push.ts`: Bare repository creation and remote configuration
+  - `src/commands/archive.ts`: Multi-step archival process (push + delete)
+  - `src/commands/restore.ts`: Repository cloning and remote renaming
+
+**E2E Tests:**
+- Not present
+- Could be valuable for validating complete workflows with actual filesystem and git operations
+
+## Common Patterns
+
+**Async Testing:**
+- Not applicable - codebase is synchronous
+- All operations use `execSync` and synchronous file I/O
+
+**Error Testing:**
+- Not applicable - no tests present
+- Current error handling in `src/errors.ts` shows pattern for testing:
+  - Custom error instances: `instanceof GitDriveError`
+  - Standard Error instances: `instanceof Error`
+  - Unknown errors: catch-all with fallback message
+
+## Current Testing Strategy
+
+**Status:** No automated tests currently in place.
+
+**Testing Approach:**
+- Manual testing via CLI commands
+- Commands throw `GitDriveError` on validation failures
+- Exit codes used: `0` for success, `1` for failure
+- User-facing error messages output to `console.error()`
+
+**Why Manual Now:**
+- Simple CLI tool with small codebase (374 lines total)
+- Requires filesystem and git operations that are environment-dependent
+- Suitable for expansion as test infrastructure is added
+
+## Recommended Testing Structure
+
+If tests are to be added, follow this structure:
+
+**Test Files Location:**
+```
+src/
+├── commands/
+│   ├── init.ts
+│   └── init.test.ts          # Co-located tests
+├── config.ts
+├── config.test.ts
+├── git.ts
+├── git.test.ts
+├── errors.ts
+└── errors.test.ts
+```
+
+**Test Dependencies Needed:**
+- Jest or Vitest as test runner
+- Mock library for fs and child_process (built-in to Jest/Vitest)
+- Temporary directory library (e.g., `fs-extra` or native `fs.mkdtempSync`)
+
+---
+
+*Testing analysis: 2026-01-22*

package/Dockerfile.cli

@@ -0,0 +1,30 @@
+# Use a Node.js base image that includes git and common utilities
+FROM node:20-alpine
+
+# Install git and util-linux (for lsblk)
+RUN apk add --no-cache git util-linux
+
+# Set working directory
+WORKDIR /app
+
+# Install pnpm
+RUN npm install -g pnpm
+
+# Copy package.json and pnpm-lock.yaml for dependency installation
+COPY package.json pnpm-lock.yaml ./
+COPY packages/cli/package.json ./packages/cli/
+COPY packages/server/package.json ./packages/server/ # Copy server's package.json too for root pnpm install
+COPY packages/ui/package.json ./packages/ui/ # Copy ui's package.json too for root pnpm install
+
+# Install dependencies for all workspaces
+RUN pnpm install --frozen-lockfile
+
+# Copy source code
+COPY . .
+
+# Build cli
+RUN pnpm build:cli
+
+# Entrypoint to run the git-drive CLI
+# This will allow 'docker run git-drive-cli <command> <args>'
+ENTRYPOINT ["pnpm", "--filter=@git-drive/cli", "start"]

package/Dockerfile.server

@@ -0,0 +1,32 @@
+# Use a Node.js base image that includes git and common utilities for node-disk-info (lsblk for linux)
+FROM node:20-alpine
+
+# Install git and util-linux (for lsblk)
+RUN apk add --no-cache git util-linux
+
+# Set working directory
+WORKDIR /app
+
+# Install pnpm
+RUN npm install -g pnpm
+
+# Copy package.json and pnpm-lock.yaml for dependency installation
+COPY package.json pnpm-lock.yaml ./
+COPY packages/server/package.json ./packages/server/
+COPY packages/ui/package.json ./packages/ui/
+COPY packages/cli/package.json ./packages/cli/ # Copy cli's package.json too for root pnpm install
+
+# Install dependencies for all workspaces
+RUN pnpm install --frozen-lockfile
+
+# Copy source code
+COPY . .
+
+# Build server and UI
+RUN pnpm build:server && pnpm build:ui
+
+# Expose the port the server runs on
+EXPOSE 4483
+
+# Command to run the server
+CMD ["pnpm", "--filter=@git-drive/server", "start"]

package/README.md

@@ -0,0 +1,95 @@
+# GIT-DRIVE
+
+Git drive is an app that can turn any connected storage volume into another git remote repo you can use to backup your code.
+
+## Installation
+
+### npm
+
+```bash
+npm install -g git-drive
+```
+
+### pnpm
+
+```bash
+pnpm add -g git-drive
+```
+
+### yarn
+
+```bash
+yarn global add git-drive
+```
+
+## Quick Start
+
+Once installed, you can use the `git-drive` command:
+
+```bash
+# Link current repo to a drive
+git-drive link
+
+# Push current repo to drive
+git-drive push
+
+# Show projects on drive
+git-drive list
+
+# Check drive and repo state
+git-drive status
+```
+
+## How it works
+
+Run the git-drive (available as a docker container). In the web ui (localhost:4483) just select the drive you want to use (this will create a `.git-drive/` directory in that drive if it doesnt already have it). Here you can see a list of existing repos in this drive (`.git-drive/*`) or add new ones so you can push your code to.
+
+Installing git-drive also installs a git-drive cli which can do all of the same things as the web ui. Users can link their current codebase to any connected drive with `git-drive link` this should create the repo in git-drive if it doesnt already exist. Then add a new remote (`git remote add git-drive .........`) and pushing to that new remote "git-drive".
+
+Git-drive can handle scenarios where multiple git-drive volumes are connected.
+
+## Docker
+
+You can also run git-drive via Docker:
+
+```bash
+# Build the Docker image
+docker compose build
+
+# Run the container
+docker compose up -d
+
+# Use the CLI through Docker
+docker compose run git-drive-cli <command>
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/josmanvis/git-drive.git
+cd git-drive
+
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Run in development mode
+pnpm dev
+```
+
+## Publishing (Maintainers)
+
+The project uses GitHub Actions for automated publishing to npm. To publish a new version:
+
+1. Update the version in `packages/cli/package.json`
+2. Create a new git tag and push to main
+3. The CI will automatically build and publish to npm
+
+Make sure to set the `NPM_TOKEN` secret in your GitHub repository settings.
+
+## License
+
+MIT

package/docker-compose.yml

@@ -0,0 +1,48 @@
+version: '3.8'
+
+services:
+  git-drive-server:
+    build:
+      context: .
+      dockerfile: Dockerfile.server
+    ports:
+      - "4483:4483"
+    volumes:
+      - git-drive-config:/root/.config/git-drive
+      # USER: Add your external drive mounts here. For example:
+      # For macOS:
+      # - /Volumes/MyExternalDrive:/mnt/MyExternalDrive
+      # For Linux:
+      # - /media/youruser/MyExternalDrive:/mnt/MyExternalDrive
+      # These paths are illustrative; you will need to adjust them to your actual drive mount points.
+    environment:
+      SERVER_URL: "http://localhost:4483" # Or the public URL if exposed
+    restart: unless-stopped
+
+  git-drive-cli:
+    build:
+      context: .
+      dockerfile: Dockerfile.cli
+    volumes:
+      - git-drive-config:/root/.config/git-drive
+      # USER: Add your external drive mounts here, same as for server.
+      # For example, to make a host repo available to the CLI:
+      # - ./my-local-repo:/app/my-local-repo
+      # And also any external drives you want the CLI to interact with:
+      # For macOS:
+      # - /Volumes/MyExternalDrive:/mnt/MyExternalDrive
+      # For Linux:
+      # - /media/youruser/MyExternalDrive:/mnt/MyExternalDrive
+      # These paths are illustrative; you will need to adjust them to your actual drive mount points.
+    depends_on:
+      - git-drive-server # Ensures config volume is initialized by server if needed.
+    # The 'git-drive-cli' service is designed to be used via `docker compose run` or `docker compose exec`.
+    # To use the CLI, you would typically run:
+    # docker compose run git-drive-cli <cli-command> <args>
+    # Or to execute a command in a running container:
+    # docker compose exec git-drive-cli <cli-command> <args>
+    # For keeping the container running in the background for exec:
+    command: ["tail", "-f", "/dev/null"]
+
+volumes:
+  git-drive-config: # For persistent git-drive configs like links.json

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "git-drive",
+  "version": "0.1.0",
+  "description": "Use an external drive as a git bare repository remote",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "pnpm build:cli && pnpm build:ui && pnpm build:server",
+    "build:cli": "tsc -p packages/cli/tsconfig.json",
+    "build:ui": "cd packages/ui && pnpm run build",
+    "build:server": "tsc -p packages/server/tsconfig.json",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "drivelist",
+      "esbuild"
+    ]
+  }
+}

package/packages/cli/Dockerfile

@@ -0,0 +1,26 @@
+# Git Drive - Docker Image
+# Includes CLI, server, and web UI
+
+FROM node:20-alpine
+
+# Install git and util-linux (for lsblk)
+RUN apk add --no-cache git util-linux
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json ./
+COPY dist ./dist/
+COPY ui ./ui/
+
+# Install production dependencies only
+RUN npm install --omit=dev
+
+# Expose the web UI port
+EXPOSE 4483
+
+# Set environment
+ENV GIT_DRIVE_PORT=4483
+
+# Default command starts the server
+CMD ["node", "dist/server.js"]