GitOcean-Old/PHASE_2_PLAN.md

# Gitocean Phase 2 Plan: Usability

Phase 2 focuses on making Gitocean feel usable as a day-to-day personal Git hosting environment. This phase is not about GitLab enterprise parity, CI/CD, or a web UI. It is about setup, common workflows, repository inspection, pull request ergonomics, and maintenance.

## Goals

- Make first-time setup simple.
- Make CLI output readable by humans by default.
- Support the common workflow of publishing an existing local repository.
- Provide enough CLI inspection tools to compensate for no web UI.
- Improve pull request workflows with diff and checkout commands.
- Add simple repository metadata and settings.
- Add lightweight collaboration support.
- Add comments, token management, and basic admin/backup tooling.

---

## 1. Config + `gitocean init`

### Add server config file

Create a persistent server config file, likely:

```text
storage/config.json
```

Example:

```json
{
  "addr": ":8080",
  "public_url": "http://localhost:8080",
  "storage": "storage",
  "mysql_dsn": "root:pass@tcp(127.0.0.1:3306)/gitocean?parseTime=true"
}
```

### Add command

```bash
gitocean init
```

It should:

1. Prompt for server listen address.
2. Prompt for public URL.
3. Prompt for storage directory.
4. Prompt for MySQL DSN or individual MySQL fields.
5. Create the database if missing.
6. Run migrations.
7. Create storage directories.
8. Optionally create the first user account.
9. Write config file.
10. Print next-step instructions.

### Update server command

Allow:

```bash
gitocean server
```

without requiring `--dsn` if config exists.

Still allow overrides:

```bash
gitocean server --config storage/config.json
```

```bash
gitocean server --dsn '...' --addr :8080 --storage storage
```

---

## 2. Friendly CLI output

Most commands currently print JSON. Phase 2 should make human-friendly output the default.

### Add global or per-command JSON output

Support:

```bash
gitocean repo search test --json
```

or eventually a global flag:

```bash
gitocean --json repo search test
```

### Examples

Repo creation should print:

```text
Created public repository owen/test

Clone:
  git clone http://localhost:8080/owen/test.git

Add existing repo:
  git remote add origin http://localhost:8080/owen/test.git
  git branch -M main
  git push -u origin main
```

Search should print a table:

```text
REPOSITORY      VISIBILITY  DESCRIPTION       UPDATED
owen/test       public      Test repository   2m ago
alice/demo      public      Demo project      3h ago
```

PR list should print:

```text
#1  open    Add config support      bob:feature-config -> main
#2  merged  Fix clone auth          alice:fix-auth -> main
```

---

## 3. `repo publish`

Add a command for publishing an existing local Git repository.

```bash
gitocean repo publish NAME --public
gitocean repo publish NAME --private
```

Optional flags:

```bash
gitocean repo publish NAME --public --remote origin
gitocean repo publish NAME --public --branch main
gitocean repo publish NAME --public --description "My project"
```

### Behavior

From inside a local Git repository:

1. Verify current directory is a Git repository.
2. Create remote repository through API.
3. Add remote if missing.
4. Set or rename current branch to `main` by default.
5. Push current branch.
6. Set upstream.
7. Print success and clone URL.

Equivalent workflow:

```bash
gitocean repo create test --public
git remote add origin http://localhost:8080/owen/test.git
git branch -M main
git push -u origin main
```

---

## 4. `repo view`, branches, tags

Since there is no web UI, add basic repository inspection commands.

### Repo view

```bash
gitocean repo view OWNER/REPO
```

Output:

```text
owen/test
Visibility: public
Default branch: main
Description: My test project

Clone:
  git clone http://localhost:8080/owen/test.git

Open PRs: 2
Branches: 4
Tags: 1
```

### Branch listing

```bash
gitocean repo branches OWNER/REPO
```

Output:

```text
BRANCH       COMMIT   UPDATED     MESSAGE
main         8f31abc  2 hours ago Initial commit
feature-x    1ab22df  1 day ago  Add feature
```

### Tag listing

```bash
gitocean repo tags OWNER/REPO
```

Output:

```text
TAG     COMMIT   DATE        MESSAGE
v0.1.0  8f31abc  2026-06-08  First release
```

### API additions

```http
GET /api/repos/{owner}/{repo}/branches
GET /api/repos/{owner}/{repo}/tags
```

---

## 5. PR diff + PR checkout

Pull requests are difficult to use without seeing and checking out changes.

### PR diff

```bash
gitocean pr diff OWNER/REPO NUMBER
```

Server should generate a diff between:

```text
source_repo:source_branch
```

and:

```text
target_repo:target_branch
```

API:

```http
GET /api/repos/{owner}/{repo}/pulls/{number}/diff
```

Return `text/plain` patch/diff output.

### PR checkout

```bash
gitocean pr checkout OWNER/REPO NUMBER
```

From inside a local Git repo, it should:

1. Fetch PR source branch from source repository URL.
2. Create or update a local branch such as `pr-1`.
3. Check out that branch.

Equivalent:

```bash
git fetch http://localhost:8080/bob/test.git fix:pr-1
git checkout pr-1
```

---

## 6. Repo description/default branch/visibility update

Add basic repository settings.

### Schema additions

Add columns to `repositories`:

- `description TEXT NOT NULL DEFAULT ''`
- `default_branch VARCHAR(200) NOT NULL DEFAULT 'main'`
- `archived BOOLEAN NOT NULL DEFAULT false`

### Commands

```bash
gitocean repo set OWNER/REPO --description "My project"
gitocean repo set OWNER/REPO --visibility private
gitocean repo set OWNER/REPO --visibility public
gitocean repo set OWNER/REPO --default-branch main
gitocean repo archive OWNER/REPO
gitocean repo unarchive OWNER/REPO
```

### API additions

```http
PATCH /api/repos/{owner}/{repo}
```

Owner-only.

---

## 7. Collaborators

Owner-only permissions are too limiting for personal collaboration. Add simple collaborators.

### Roles

- `read`: can clone/fetch private repositories.
- `write`: can clone/fetch/push.

Owner remains the only user who can:

- delete repository
- update settings
- manage collaborators
- merge/close PRs, unless explicitly changed later

### Schema

Add table:

```text
repository_collaborators
  id
  repository_id
  user_id
  role: read/write
  created_at
```

Unique key:

```text
(repository_id, user_id)
```

### Commands

```bash
gitocean repo collaborators OWNER/REPO
gitocean repo collaborator add OWNER/REPO USER --role read
gitocean repo collaborator add OWNER/REPO USER --role write
gitocean repo collaborator remove OWNER/REPO USER
```

### API additions

```http
GET    /api/repos/{owner}/{repo}/collaborators
POST   /api/repos/{owner}/{repo}/collaborators
DELETE /api/repos/{owner}/{repo}/collaborators/{username}
```

---

## 8. PR comments

Add simple general comments on pull requests. Line comments can wait.

### Schema

Add table:

```text
pull_request_comments
  id
  pull_request_id
  author_user_id
  body
  created_at
  updated_at
```

### Commands

```bash
gitocean pr comment OWNER/REPO NUMBER "Looks good"
gitocean pr comments OWNER/REPO NUMBER
```

Optional editor support later:

```bash
gitocean pr comment OWNER/REPO NUMBER --editor
```

### API additions

```http
GET  /api/repos/{owner}/{repo}/pulls/{number}/comments
POST /api/repos/{owner}/{repo}/pulls/{number}/comments
```

---

## 9. Token management

Tokens expire after 7 days, but users need visibility and revocation.

### Commands

```bash
gitocean token list
gitocean token revoke TOKEN_ID
gitocean token prune
```

### Behavior

- `token list`: show active tokens for current user.
- `token revoke`: revoke one token.
- `token prune`: remove expired/revoked tokens from database. Owner/admin-only if global, current-user only otherwise.

### API additions

```http
GET    /api/tokens
DELETE /api/tokens/{id}
POST   /api/tokens/prune
```

### CLI expired-session UX

When API returns unauthorized, show:

```text
Your session may have expired. Run:
  gitocean login
```

---

## 10. Backup/admin commands

Personal servers need reliable maintenance tooling.

### Admin commands

```bash
gitocean admin users list
gitocean admin users delete USER
gitocean admin repos list
gitocean admin storage check
gitocean admin tokens prune
```

For MVP, admin can be:

- the first registered user, or
- a boolean `is_admin` column on `users`.

### Backup commands

```bash
gitocean backup create backup.tar.gz
gitocean backup restore backup.tar.gz
```

Backup should include:

- server config
- `storage/repos/`
- MySQL dump of metadata

Possible implementation:

```bash
mysqldump ... > metadata.sql
tar -czf backup.tar.gz storage/config.json storage/repos metadata.sql
```

Restore should:

1. Stop or warn about running server.
2. Restore config.
3. Restore repositories.
4. Restore database from SQL dump.
5. Run migrations after restore.

---

## Recommended implementation order

1. Config file support and `gitocean init`.
2. Friendly CLI output with `--json` escape hatch.
3. `repo publish`.
4. Repository metadata fields and `repo view`.
5. Branch/tag listing.
6. PR diff.
7. PR checkout.
8. Collaborators.
9. PR comments.
10. Token management.
11. Backup/admin commands.

## Success criteria

Phase 2 is successful when a user can comfortably:

1. Initialize the server without memorizing flags.
2. Register/login from CLI.
3. Publish an existing local Git repository with one command.
4. Clone, push, search, and inspect repositories.
5. Open, inspect, checkout, and merge PRs.
6. Share private repositories with specific users.
7. Revoke tokens and back up the server.