@aaronshaf/ger 1.2.10 → 2.0.0

package/bunfig.toml

@@ -0,0 +1,8 @@
+[test]
+# Test configuration
+coverage = true
+coverageThreshold = { line = 80.0, function = 80.0, statement = 80.0, branch = 80.0 }
+coverageReporter = ["text", "lcov"]
+coverageSkipTestFiles = true
+# Exclude patterns from coverage
+coverageExclude = ["node_modules", "dist", "tmp", "tests/mocks", "**/*.d.ts"]

package/docs/adr/0001-use-effect-for-side-effects.md

@@ -0,0 +1,65 @@
+# ADR 0001: Use Effect for Side Effects
+
+## Status
+
+Accepted
+
+## Context
+
+We need to decide on a strategy for handling side effects (API calls, file I/O, errors) in the `ger` CLI. Options considered:
+
+1. **Traditional try/catch** - Simple but errors lose type information
+2. **Result types (manual)** - Explicit but verbose
+3. **Effect library** - Type-safe, composable, full dependency injection
+
+## Decision
+
+Use the Effect library for all side effects and dependency injection.
+
+## Rationale
+
+- **Type-safe errors**: Effect tracks error types at compile time via tagged unions
+- **Composability**: Operations compose naturally with `Effect.gen` and `pipe()`
+- **Dependency injection**: Layers provide testable, swappable dependencies
+- **Resource management**: `Effect.scoped` handles cleanup automatically
+- **Concurrent operations**: Effect handles parallelism safely
+
+## Consequences
+
+### Positive
+- Compile-time error tracking with `Effect.catchTag`
+- Clear error handling paths without try/catch
+- Testable services via Layer injection
+- No runtime surprises from unhandled errors
+
+### Negative
+- Learning curve for Effect newcomers
+- Additional dependency (~100KB)
+- More verbose than simple async/await
+- Requires understanding of functional programming patterns
+
+## Example
+
+```typescript
+// Tagged error types
+export class ApiError extends Schema.TaggedError<ApiError>()('ApiError', {
+  message: Schema.String,
+  statusCode: Schema.Number,
+}) {}
+
+// Effect-based service
+export const getChange = (changeId: string): Effect.Effect<ChangeInfo, ApiError, GerritApiService> =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+    const change = yield* api.getChange(changeId)
+    return change
+  })
+
+// Provide dependencies via layers
+Effect.runPromise(
+  getChange('12345').pipe(
+    Effect.provide(GerritApiServiceLive),
+    Effect.provide(ConfigServiceLive)
+  )
+)
+```

package/docs/adr/0002-use-bun-runtime.md

@@ -0,0 +1,64 @@
+# ADR 0002: Use Bun Runtime
+
+## Status
+
+Accepted
+
+## Context
+
+We need to choose a JavaScript/TypeScript runtime for the CLI tool. Options considered:
+
+1. **Node.js** - Most common, widely supported
+2. **Deno** - Modern, secure by default, built-in TypeScript
+3. **Bun** - Fast, native TypeScript, all-in-one toolchain
+
+## Decision
+
+Use Bun 1.2.0+ as the runtime.
+
+## Rationale
+
+- **Native TypeScript**: No compilation step needed, run `.ts` files directly
+- **Speed**: Faster startup time than Node.js (~4x faster cold start)
+- **All-in-one**: Package manager, test runner, bundler included
+- **SQLite built-in**: Native SQLite support for future caching needs
+- **Consistency**: Matches `ji` and `cn` projects (same author)
+
+## Consequences
+
+### Positive
+- No separate build step for development
+- Faster CLI startup time (important for frequently-run tool)
+- Single tool for package management, testing, and running
+- Built-in test runner with coverage support
+
+### Negative
+- Smaller ecosystem than Node.js
+- Some npm packages may have compatibility issues
+- Users must install Bun (not pre-installed like Node on many systems)
+- Breaking changes between Bun versions possible
+
+## Version Requirements
+
+```typescript
+// src/cli/index.ts
+const [major, minor] = Bun.version.split('.').map(Number)
+if (major < 1 || (major === 1 && minor < 2)) {
+  console.error('ger requires Bun 1.2.0 or later')
+  process.exit(1)
+}
+```
+
+## Build Configuration
+
+```json
+// package.json
+{
+  "type": "module",
+  "scripts": {
+    "build": "tsc --noEmit && echo 'Build successful - CLI runs directly with bun'",
+    "dev": "bun run src/cli/index.ts",
+    "test": "bun test"
+  }
+}
+```

package/docs/adr/0003-store-credentials-in-home-directory.md

@@ -0,0 +1,75 @@
+# ADR 0003: Store Credentials in Home Directory
+
+## Status
+
+Accepted
+
+## Context
+
+We need to store Gerrit authentication credentials (host, username, HTTP password/token). Options considered:
+
+1. **Environment variables only** - Simple but inconvenient for interactive use
+2. **Project-local config** - Risk of committing credentials
+3. **System keychain** - Secure but platform-specific complexity
+4. **Home directory file** - Portable, standard pattern
+
+## Decision
+
+Store credentials in `~/.ger/config.json` with environment variable fallback.
+
+## Rationale
+
+- **Standard pattern**: Matches Git, SSH, AWS CLI conventions
+- **Persistent**: Survives terminal sessions
+- **Secure**: File permissions set to 0600 (owner read/write only)
+- **CI-friendly**: Environment variables work in pipelines
+- **Portable**: Same approach across macOS, Linux, WSL
+
+## Consequences
+
+### Positive
+- Single setup command configures everything
+- Works offline once configured
+- Environment variables for CI/CD pipelines
+- Matches user expectations from other CLIs
+
+### Negative
+- File stored in plaintext (mitigated by permissions)
+- Users must trust file system security
+- Migration needed when format changes
+
+## Implementation
+
+```typescript
+const CONFIG_DIR = path.join(os.homedir(), '.ger')
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json')
+
+// Set secure permissions
+fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 })
+fs.writeFileSync(CONFIG_FILE, JSON.stringify(config), { mode: 0o600 })
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `GERRIT_HOST` | Gerrit server URL |
+| `GERRIT_USERNAME` | Username for authentication |
+| `GERRIT_PASSWORD` | HTTP password or API token |
+
+## Priority Order
+
+1. File configuration (`~/.ger/config.json`)
+2. Environment variables
+3. Error (no credentials found)
+
+## Migration Support
+
+Automatically migrates legacy nested format:
+```json
+// Old format
+{ "credentials": { "host": "...", "username": "..." } }
+
+// New flat format
+{ "host": "...", "username": "..." }
+```

package/docs/adr/0004-use-commander-for-cli.md

@@ -0,0 +1,76 @@
+# ADR 0004: Use Commander.js for CLI Framework
+
+## Status
+
+Accepted
+
+## Context
+
+We need a CLI framework for argument parsing, command routing, and help generation. Options considered:
+
+1. **Ink** - React-like components for terminal UIs
+2. **Commander.js** - Classic, stable CLI framework
+3. **Yargs** - Feature-rich, complex API
+4. **Clipanion** - Type-safe, used by Yarn
+
+## Decision
+
+Use Commander.js for the CLI framework, with Inquirer for interactive prompts.
+
+## Rationale
+
+- **Stability**: Most downloaded CLI framework, battle-tested
+- **Simplicity**: Straightforward API for defining commands
+- **Features**: Built-in help, version, option parsing
+- **Ecosystem**: Wide community support and documentation
+- **Consistency**: Matches patterns from other tools
+
+## Consequences
+
+### Positive
+- Simple command definition with `.command()`, `.option()`, `.action()`
+- Automatic `--help` and `--version` generation
+- Subcommand support for complex CLIs
+- Well-documented with many examples
+
+### Negative
+- Not as type-safe as Clipanion
+- Less suitable for complex interactive UIs (use Inquirer instead)
+- Callback-based API (wrapped with Effect)
+
+## Implementation
+
+```typescript
+// src/cli/index.ts
+import { Command } from 'commander'
+
+const program = new Command()
+  .name('ger')
+  .description('Gerrit CLI tool')
+  .version(version)
+
+// Register commands
+program
+  .command('show [change-id]')
+  .description('Show change details')
+  .option('--xml', 'Output as XML')
+  .action((changeId, options) => {
+    // Wrapped in Effect.runPromise
+  })
+```
+
+## Interactive Prompts
+
+For interactive input, use `@inquirer/prompts`:
+
+```typescript
+import { input, select } from '@inquirer/prompts'
+
+const changeId = await select({
+  message: 'Select a change to abandon:',
+  choices: changes.map(c => ({
+    name: `${c._number}: ${c.subject}`,
+    value: String(c._number)
+  }))
+})
+```

package/docs/adr/0005-use-effect-schema-for-validation.md

@@ -0,0 +1,93 @@
+# ADR 0005: Use Effect Schema for Data Validation
+
+## Status
+
+Accepted
+
+## Context
+
+We need to validate data from external sources (Gerrit API, user input, config files). Options considered:
+
+1. **Zod** - Popular, simple API, runtime validation
+2. **io-ts** - Functional, integrates with fp-ts
+3. **Effect Schema** - Part of Effect ecosystem, type inference
+4. **Manual validation** - No dependencies, full control
+
+## Decision
+
+Use Effect Schema for all data validation.
+
+## Rationale
+
+- **Effect integration**: Seamless with Effect error handling
+- **Single source of truth**: Schema defines type AND validation
+- **Composable**: Schemas compose with `Schema.Struct`, `Schema.Array`, etc.
+- **Branded types**: Support for refined types with constraints
+- **Decode/Encode**: Bidirectional transformations supported
+
+## Consequences
+
+### Positive
+- Types inferred from schemas automatically
+- Validation errors are structured, not strings
+- Reusable in tests with MSW mock validation
+- Compile-time and runtime safety
+
+### Negative
+- Learning curve for Schema DSL
+- Larger bundle than Zod
+- Less documentation than mainstream libraries
+
+## Implementation
+
+```typescript
+// src/schemas/gerrit.ts
+import { Schema } from '@effect/schema'
+
+export const ChangeInfo = Schema.Struct({
+  id: Schema.String,
+  _number: Schema.Number,
+  project: Schema.String,
+  branch: Schema.String,
+  subject: Schema.String,
+  status: Schema.Literal('NEW', 'MERGED', 'ABANDONED', 'DRAFT'),
+  owner: Schema.Struct({
+    _account_id: Schema.Number,
+    name: Schema.optional(Schema.String),
+    email: Schema.optional(Schema.String),
+  }),
+  created: Schema.String,
+  updated: Schema.String,
+})
+
+// Type is inferred
+export type ChangeInfo = Schema.Schema.Type<typeof ChangeInfo>
+```
+
+## Tagged Errors
+
+Effect Schema supports tagged errors for type-safe error handling:
+
+```typescript
+export class ApiError extends Schema.TaggedError<ApiError>()('ApiError', {
+  message: Schema.String,
+  statusCode: Schema.Number,
+  url: Schema.String,
+}) {}
+
+// Usage
+Effect.catchTag('ApiError', (error) => {
+  console.error(`API failed: ${error.message} (${error.statusCode})`)
+})
+```
+
+## Validation in API Layer
+
+```typescript
+const parseResponse = <T>(schema: Schema.Schema<T>, data: unknown): Effect.Effect<T, ApiError> =>
+  Schema.decodeUnknown(schema)(data).pipe(
+    Effect.mapError((parseError) =>
+      new ApiError({ message: 'Invalid response format', statusCode: 500, url: '' })
+    )
+  )
+```

package/docs/adr/0006-use-msw-for-api-mocking.md

@@ -0,0 +1,89 @@
+# ADR 0006: Use MSW for API Mocking
+
+## Status
+
+Accepted
+
+## Context
+
+We need to mock HTTP requests in tests without making real API calls. Options considered:
+
+1. **nock** - Classic Node.js HTTP mocking
+2. **MSW (Mock Service Worker)** - Request interception at network level
+3. **fetch-mock** - Simple fetch mocking
+4. **Manual mocks** - Jest/Vitest manual module mocks
+
+## Decision
+
+Use MSW (Mock Service Worker) for all HTTP request mocking in tests.
+
+## Rationale
+
+- **Network level**: Intercepts at fetch/HTTP level, not module level
+- **Realistic**: Tests actual HTTP behavior, not mocked modules
+- **Reusable handlers**: Define once, use across many tests
+- **Schema validation**: Mock responses can validate against Effect Schemas
+- **Framework agnostic**: Works with any test runner
+
+## Consequences
+
+### Positive
+- Tests exercise real HTTP client code
+- Handlers are portable and reusable
+- Easy to simulate error conditions (timeouts, 500s)
+- No module mocking complexity
+
+### Negative
+- Additional dependency
+- Requires setup/teardown in tests
+- Learning MSW handler syntax
+
+## Implementation
+
+```typescript
+// tests/mocks/handlers.ts
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+  http.get('*/a/changes/:changeId', ({ params }) => {
+    return HttpResponse.json({
+      id: 'project~main~I1234567890abcdef',
+      _number: parseInt(params.changeId as string),
+      project: 'test-project',
+      branch: 'main',
+      subject: 'Test change',
+      status: 'NEW',
+      // ... schema-compliant response
+    })
+  }),
+
+  http.post('*/a/changes/:changeId/revisions/current/review', () => {
+    return new HttpResponse(null, { status: 200 })
+  }),
+]
+```
+
+## Test Setup
+
+```typescript
+// tests/setup.ts
+import { setupServer } from 'msw/node'
+import { handlers } from './mocks/handlers'
+
+export const server = setupServer(...handlers)
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+
+## Error Simulation
+
+```typescript
+// Simulate API errors in specific tests
+server.use(
+  http.get('*/a/changes/:changeId', () => {
+    return new HttpResponse(null, { status: 404 })
+  })
+)
+```

package/docs/adr/0007-git-hooks-for-quality.md

@@ -0,0 +1,94 @@
+# ADR 0007: Git Hooks for Code Quality
+
+## Status
+
+Accepted
+
+## Context
+
+We need to enforce code quality standards automatically. Options considered:
+
+1. **CI-only checks** - Run in pipeline, no local enforcement
+2. **Manual commands** - Developers run checks before committing
+3. **Git hooks** - Automatic checks on commit/push
+4. **IDE integration** - Real-time feedback in editor
+
+## Decision
+
+Use Husky + lint-staged for pre-commit hooks, with additional pre-push validation.
+
+## Rationale
+
+- **Automatic enforcement**: Can't forget to run checks
+- **Fast feedback**: Catch issues before push, not in CI
+- **Staged files only**: lint-staged only checks changed files (fast)
+- **Consistent**: All developers run same checks
+
+## Consequences
+
+### Positive
+- Consistent code quality across all commits
+- Fast local feedback
+- Prevents broken commits from reaching CI
+- Staged-only linting is fast
+
+### Negative
+- Initial setup required (Husky install)
+- Can slow down commits if checks are slow
+- Developers may skip with `--no-verify` (discouraged)
+
+## Pre-commit Checks
+
+```bash
+# .husky/pre-commit
+bun lint-staged
+bun run scripts/check-file-size.ts
+```
+
+## lint-staged Configuration
+
+```json
+// package.json
+{
+  "lint-staged": {
+    "*.ts": [
+      "biome format --write",
+      "oxlint"
+    ]
+  }
+}
+```
+
+## Pre-push Checks
+
+```bash
+# .husky/pre-push
+bun run build
+bun test
+bun run test:coverage:check
+```
+
+## File Size Enforcement
+
+Custom script checks file lengths:
+
+```typescript
+// scripts/check-file-size.ts
+const WARN_THRESHOLD = 500  // lines
+const ERROR_THRESHOLD = 700 // lines
+
+// Warn at 500, error at 700 lines
+// Excludes: generated files, tmp/, node_modules/
+```
+
+## Coverage Enforcement
+
+```typescript
+// scripts/check-coverage.ts
+const THRESHOLDS = {
+  line: 80,
+  function: 80,
+  statement: 80,
+  branch: 80,
+}
+```

package/docs/adr/0008-no-as-typecasting.md

@@ -0,0 +1,83 @@
+# ADR 0008: Prohibit `as` Type Casting
+
+## Status
+
+Accepted
+
+## Context
+
+TypeScript's `as` keyword allows bypassing type safety. This can hide bugs and defeat the purpose of type checking. We need a policy on type assertions.
+
+## Decision
+
+Prohibit `as` type casting except for `as const` and `as unknown` (required for Effect Schema workarounds).
+
+## Rationale
+
+- **Type safety**: `as` bypasses TypeScript's guarantees
+- **Hidden bugs**: Incorrect casts cause runtime errors
+- **Better alternatives**: Type guards, generics, schema validation
+- **Code review**: Hard to catch incorrect casts in review
+
+## Exceptions
+
+### Allowed: `as const`
+
+```typescript
+// Allowed - creates literal types
+const statuses = ['NEW', 'MERGED', 'ABANDONED'] as const
+```
+
+### Allowed: `as unknown` (Effect Schema workaround)
+
+```typescript
+// Required for Effect Schema TaggedError pattern
+export class ApiError
+  extends (ApiErrorSchema as unknown as new (
+    args: ApiErrorFields,
+  ) => ApiErrorFields & Error & { readonly _tag: 'ApiError' })
+  implements Error
+{ ... }
+```
+
+## Consequences
+
+### Positive
+- Compile-time errors instead of runtime crashes
+- Forces proper type design
+- More maintainable code
+- Better IDE support
+
+### Negative
+- More verbose in some cases
+- Effect Schema requires workarounds
+- Learning curve for developers used to `as`
+
+## Enforcement
+
+ast-grep rules (in progress):
+
+```yaml
+# sgconfig.yml
+rules:
+  - id: no-as-casting
+    pattern: $EXPR as $TYPE
+    except:
+      - $EXPR as const
+      - $EXPR as unknown
+    message: "Avoid 'as' type casting. Use type guards or schema validation."
+```
+
+## Alternatives to `as`
+
+```typescript
+// Instead of: const x = data as ChangeInfo
+
+// Use schema validation
+const x = Schema.decodeUnknownSync(ChangeInfo)(data)
+
+// Or type guards
+function isChangeInfo(data: unknown): data is ChangeInfo {
+  return typeof data === 'object' && data !== null && '_number' in data
+}
+```