Gogh Repository Manager Guide

This skill provides expert guidance for working on the gogh project, a tool for managing GitHub repositories efficiently inspired by `ghq`.

Project Overview

Gogh is located at `github.com/kyoh86/gogh` and follows clean architecture principles with clear layer separation.

Output Language Convention

Architecture

Four-Layer Structure

The project follows a strict layered architecture with clear dependency rules:

```

UI Layer (ui/)

↓ depends on

Application Layer (app/)

↓ depends on

Core Layer (core/)

↑ implements

Infrastructure Layer (infra/)

```

Layer Descriptions

1. **Core Layer (`core/`)** - Innermost layer

- Domain entities and interface definitions

- No dependencies on other layers

- Contains:

- `auth/` - Authentication interfaces

- `git/` - Git operation interfaces

- `hosting/` - Repository hosting service interfaces

- `repository/` - Repository models and path operations

- `store/` - Data persistence interfaces

- `workspace/` - Workspace management interfaces

- `*_mock/` - Mock packages for each interface

2. **Application Layer (`app/`)** - Use case orchestration

- Only imports from core layer

- Coordinates core functionalities

- Contains:

- `auth/` - Authentication use cases

- `bundle/` - Batch repository management

- `clone/` - Clone operations

- `fork/` - Fork operations

- `repos/` - Repository listing

- `service/` - Common services

3. **Infrastructure Layer (`infra/`)** - External integrations

- Implements core layer interfaces

- Only imports from core layer

- Contains:

- `auth/` - Authentication implementation

- `git/` - Git operation implementation

- `github/` - GitHub API integration

- `store/` - Data persistence implementation

- `workspace/` - Workspace management implementation

4. **UI Layer (`ui/`)** - User interfaces

- Can import from application layer

- Contains:

- `cli/commands/` - Cobra-based CLI commands

Testing Conventions

Test File Organization

1. **Private function tests**:

- Filename: `_private_test.go`

- Package: Same as source (e.g., `package mypackage`)

- Tests private implementation details

2. **Public API tests**:

- Filename: `*_test.go`

- Package: Source package + `_test` suffix (e.g., `package mypackage_test`)

- Import tested package as `testtarget`

- Tests public interface

Testing Framework

Example Test Structure

```go

// Public API test

package mypackage_test

import (

"testing"

testtarget "github.com/kyoh86/gogh/v4/mypackage"

)

func TestPublicFunction(t *testing.T) {

// Test implementation

}

```

Mock Generation

Mock Location and Naming

Generation Setup

Example Mock Generation

```go

// gen.go

package repository

//go:generate go run go.uber.org/mock/mockgen -destination=../repository_mock/gen_default_name_service_mock.go -package=repository_mock github.com/kyoh86/gogh/v4/core/repository DefaultNameService

```

Package Versioning

Core Concepts

Repository Reference Format

Repository Components

Basic Operations

Dependency Rules (Critical)

When writing or modifying code, strictly follow these rules:

1. **Core layer**: MUST NOT import from any other layer

2. **Application layer**: MAY ONLY import from core layer

3. **Infrastructure layer**: MAY ONLY import from core layer

4. **UI layer**: MAY import from application layer

Violations of these rules break the architecture. Always validate import paths.

Best Practices

1. Define interfaces in core layer before implementation

2. Use interface-based integration for testability

3. Keep domain logic in core layer, pure and framework-free

4. Implement concrete integrations in infrastructure layer

5. Orchestrate use cases in application layer

6. Keep UI layer thin, delegating to application layer

7. Write tests for both public APIs and private implementations

8. Generate mocks for all interfaces used in tests

9. Follow the established directory structure strictly

Common Tasks

Adding a New Feature

1. Define domain entities/interfaces in `core/`

2. Create mock package and generation setup

3. Implement use case in `app/`

4. Implement external integrations in `infra/`

5. Add CLI command in `ui/cli/commands/`

6. Write tests for each layer

Modifying Existing Code

1. Check which layer the code belongs to

2. Verify dependency rules are followed

3. Update tests (both public and private if needed)

4. Regenerate mocks if interfaces changed

5. Update related documentation