Skip to content

Commit c0e181e

Browse files
ErcinDedeogluErcinDedeoglu
committed
feat(docs): update configuration documentation and change license to AGPL-3.0
1 parent 400fa92 commit c0e181e

3 files changed

Lines changed: 133 additions & 142 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -68,100 +68,16 @@ Configure in `opencode-sync.json`:
6868

6969
## Configuration
7070

71-
### Quick Start
72-
7371
1. Create a [GitHub Personal Access Token](https://github.com/settings/tokens) with `repo` scope
74-
2. Set the environment variable:
72+
2. Set environment variable:
7573

7674
```bash
7775
export GITHUB_TOKEN=ghp_your_token_here
7876
```
7977

80-
3. Start OpenCode - the plugin will automatically create a private repo for sync storage
81-
82-
Add to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence.
83-
84-
### What Happens on First Run
85-
86-
When the plugin starts with a valid token but no storage configured:
87-
1. Detects your GitHub username automatically
88-
2. Creates a new **private** repository called `.opencode-sync`
89-
3. Initializes the `.opencode-sync/` directory with a manifest
90-
4. Saves the repo info to `~/.config/opencode/opencode-sync.json`
91-
5. Future runs will use the same repository
92-
93-
### Alternative: Config File
94-
95-
Instead of environment variable, create `~/.config/opencode/opencode-sync.json`:
96-
97-
```json
98-
{
99-
"token": "ghp_your_token_here"
100-
}
101-
```
102-
103-
### Token Priority
104-
105-
Config file token takes precedence over environment variable.
106-
107-
### Verifying Configuration
108-
109-
After starting OpenCode, check the logs for:
110-
```
111-
[opencode-sync] Token loaded from: environment variable
112-
[opencode-sync] Setting up sync storage...
113-
[opencode-sync] Creating sync repository...
114-
[opencode-sync] Linked to repo: username/.opencode-sync
115-
[opencode-sync] Repo saved to config
116-
[opencode-sync] Plugin ready
117-
```
118-
119-
On subsequent runs:
120-
```
121-
[opencode-sync] Token loaded from: environment variable
122-
[opencode-sync] Linked to repo: username/.opencode-sync
123-
[opencode-sync] Plugin ready
124-
```
125-
126-
### Full Configuration Options
127-
128-
```json
129-
{
130-
"token": "ghp_your_token_here",
131-
"repoOwner": "auto-detected-username",
132-
"repoName": ".opencode-sync",
133-
"autoSyncOnStartup": true,
134-
"continuousSync": true,
135-
"syncIntervalMinutes": 5,
136-
"fileWatcherDebounceMs": 5000,
137-
"maxDebounceMs": 30000,
138-
"sync": {
139-
"config": true,
140-
"state": true,
141-
"credentials": true,
142-
"sessions": true,
143-
"messages": true,
144-
"projects": true,
145-
"todos": true
146-
},
147-
"conflictStrategy": "auto-merge"
148-
}
149-
```
150-
151-
**Note:** All categories are enabled by default. Disable `messages` if you have very large conversation history (8MB+) and want to reduce sync size.
152-
153-
## Sync Timing
154-
155-
The plugin uses **activity-aware batching** to prevent excessive syncs during heavy IO:
78+
3. Start OpenCode - the plugin automatically creates a private repo for sync storage
15679

157-
| Trigger | Default | Description |
158-
|---------|---------|-------------|
159-
| **Startup** | Enabled | Immediately when OpenCode starts |
160-
| **File Changes** | 5s debounce | Wait for inactivity before syncing |
161-
| **Max Delay** | 30s cap | Force sync even during heavy activity |
162-
| **Interval** | 5 minutes | Periodic sync regardless of changes |
163-
164-
During heavy activity, syncs are batched and fire at most every 30 seconds.
80+
See [Configuration Guide](docs/CONFIG.md) for all options.
16581

16682
## Security
16783

@@ -175,66 +91,14 @@ During heavy activity, syncs are batched and fire at most every 30 seconds.
17591

17692
| Guide | Description |
17793
|-------|-------------|
94+
| [Configuration](docs/CONFIG.md) | All configuration options |
17895
| [Architecture](docs/ARCHITECTURE.md) | Code structure and modules |
17996
| [Sync Architecture](docs/SYNC.md) | Sync triggers, batching, data categories |
18097
| [Sync Paths](docs/SYNC-PATHS.md) | OpenCode file locations by platform |
18198
| [Development Setup](docs/DEV-SETUP.md) | Local development environment |
18299
| [Publishing](docs/PUBLISH.md) | npm release process |
183100
| [LLM Installation](docs/LLM-INSTALL.md) | Instructions for AI coding agents |
184101

185-
## Development
186-
187-
```bash
188-
# Install dependencies
189-
npm install
190-
191-
# Build
192-
npm run build
193-
194-
# Watch mode
195-
npm run dev
196-
197-
# Run all checks (typecheck + lint + format)
198-
npm run check
199-
200-
# Lint only
201-
npm run lint
202-
203-
# Lint and fix
204-
npm run lint:fix
205-
206-
# Type check only
207-
npm run typecheck
208-
209-
# Format code
210-
npm run format
211-
```
212-
213-
## Code Quality
214-
215-
This project uses strict linting rules optimized for LLM readability and maintainability:
216-
217-
### File & Function Limits
218-
- Max **200 lines** per file (excluding blanks/comments)
219-
- Max **60 lines** per function
220-
- Max **4 levels** of nesting
221-
- Max **5 parameters** per function
222-
- Max **20 statements** per function
223-
- Cyclomatic complexity limit of **15**
224-
225-
### TypeScript Strictness
226-
- Explicit return types required
227-
- Explicit member accessibility required
228-
- No `any` types allowed
229-
- No floating promises
230-
- Consistent type imports/exports
231-
232-
### Pre-commit Hooks
233-
Husky + lint-staged runs automatically on commit:
234-
1. Full TypeScript type checking
235-
2. ESLint with auto-fix on staged files
236-
3. Prettier formatting on staged files
237-
238102
## License
239103

240-
MIT
104+
AGPL-3.0

‎docs/CONFIG.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Configuration
2+
3+
## Quick Start
4+
5+
1. Create a [GitHub Personal Access Token](https://github.com/settings/tokens) with `repo` scope
6+
2. Set environment variable:
7+
8+
```bash
9+
export GITHUB_TOKEN=ghp_your_token_here
10+
```
11+
12+
3. Start OpenCode - the plugin automatically creates a private repo for sync storage
13+
14+
Add to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence.
15+
16+
## Alternative: Config File
17+
18+
Instead of environment variable, create `~/.config/opencode/opencode-sync.json`:
19+
20+
```json
21+
{
22+
"token": "ghp_your_token_here"
23+
}
24+
```
25+
26+
Config file token takes precedence over environment variable.
27+
28+
## What Happens on First Run
29+
30+
When the plugin starts with a valid token but no storage configured:
31+
32+
1. Detects your GitHub username automatically
33+
2. Creates a new **private** repository called `.opencode-sync`
34+
3. Initializes the `.opencode-sync/` directory with a manifest
35+
4. Saves the repo info to `~/.config/opencode/opencode-sync.json`
36+
5. Future runs will use the same repository
37+
38+
## Verifying Configuration
39+
40+
After starting OpenCode, check the logs for:
41+
42+
```
43+
[opencode-sync] Token loaded from: environment variable
44+
[opencode-sync] Setting up sync storage...
45+
[opencode-sync] Creating sync repository...
46+
[opencode-sync] Linked to repo: username/.opencode-sync
47+
[opencode-sync] Repo saved to config
48+
[opencode-sync] Plugin ready
49+
```
50+
51+
On subsequent runs:
52+
53+
```
54+
[opencode-sync] Token loaded from: environment variable
55+
[opencode-sync] Linked to repo: username/.opencode-sync
56+
[opencode-sync] Plugin ready
57+
```
58+
59+
## Full Configuration Options
60+
61+
| Option | Type | Default | Description |
62+
|--------|------|---------|-------------|
63+
| `token` | string | - | GitHub PAT with `repo` scope (required) |
64+
| `repoOwner` | string | auto | GitHub username (auto-detected) |
65+
| `repoName` | string | `.opencode-sync` | Repository name for sync storage |
66+
| `branch` | string | auto | Branch name (auto-detected: main/master) |
67+
| `autoSyncOnStartup` | boolean | `true` | Sync when OpenCode starts |
68+
| `continuousSync` | boolean | `true` | Watch files and sync on changes |
69+
| `syncIntervalMinutes` | number | `5` | Periodic sync interval |
70+
| `fileWatcherDebounceMs` | number | `5000` | Wait after file change before sync |
71+
| `maxDebounceMs` | number | `30000` | Max wait during heavy activity |
72+
| `conflictStrategy` | string | `auto-merge` | How to resolve conflicts |
73+
74+
## Sync Categories
75+
76+
Control what gets synced:
77+
78+
```json
79+
{
80+
"sync": {
81+
"config": true,
82+
"state": true,
83+
"credentials": true,
84+
"sessions": true,
85+
"messages": true,
86+
"projects": true,
87+
"todos": true
88+
}
89+
}
90+
```
91+
92+
All categories are enabled by default. Disable `messages` if you have very large conversation history (8MB+).
93+
94+
## Conflict Strategies
95+
96+
| Strategy | Description |
97+
|----------|-------------|
98+
| `auto-merge` | Attempt automatic three-way merge (default) |
99+
| `local-wins` | Keep local changes on conflict |
100+
| `remote-wins` | Keep remote changes on conflict |
101+
| `newest-wins` | Keep whichever is newer |
102+
| `ask` | Prompt for resolution |
103+
104+
## Example: Full Config
105+
106+
```json
107+
{
108+
"token": "ghp_your_token_here",
109+
"repoOwner": "auto-detected-username",
110+
"repoName": ".opencode-sync",
111+
"autoSyncOnStartup": true,
112+
"continuousSync": true,
113+
"syncIntervalMinutes": 5,
114+
"fileWatcherDebounceMs": 5000,
115+
"maxDebounceMs": 30000,
116+
"sync": {
117+
"config": true,
118+
"state": true,
119+
"credentials": true,
120+
"sessions": true,
121+
"messages": true,
122+
"projects": true,
123+
"todos": true
124+
},
125+
"conflictStrategy": "auto-merge"
126+
}
127+
```

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@
3737
"multi-machine"
3838
],
3939
"author": "Ercin Dedeoglu",
40-
"license": "MIT",
40+
"license": "AGPL-3.0",
4141
"dependencies": {
4242
"@opencode-ai/plugin": "latest",
4343
"pako": "^2.1.0"

0 commit comments

Comments
 (0)