Skip to content

Commit d1cbe62

Browse files
yriveiroyriveiro
committed
feat: first commit
0 parents  commit d1cbe62

24 files changed

+1538
-0
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- uses: oven-sh/setup-bun@v2
17+
with:
18+
bun-version: latest
19+
20+
- name: Install dependencies
21+
run: bun install
22+
23+
- name: Type check
24+
run: bun run typecheck
25+
26+
- name: Lint
27+
run: bun run lint
28+
29+
- name: Check format
30+
run: bun run check
31+
32+
- name: Test
33+
run: bun test

‎.github/workflows/release.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
workflow_dispatch:
8+
9+
jobs:
10+
publish:
11+
runs-on: ubuntu-latest
12+
13+
permissions:
14+
contents: read
15+
id-token: write
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- uses: oven-sh/setup-bun@v2
21+
with:
22+
bun-version: latest
23+
24+
- uses: actions/setup-node@v4
25+
with:
26+
node-version: 'lts/*'
27+
registry-url: 'https://registry.npmjs.org'
28+
29+
- name: Update npm
30+
run: npm install -g npm@latest
31+
32+
- name: Install dependencies
33+
run: bun install
34+
35+
- name: Build
36+
run: bun run build
37+
38+
- name: Publish to npm
39+
run: npm publish --provenance --access public

‎.gitignore‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
7+
# Lock files (use bun.lock instead)
8+
package-lock.json
9+
yarn.lock
10+
11+
# OS files
12+
.DS_Store
13+
14+
# IDE
15+
.idea/
16+
.vscode/
17+
18+
# Cache
19+
.cache/

‎.gitmessage‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Commit Message Template
2+
#
3+
# Format: <type>(<scope>): <subject>
4+
#
5+
# Types:
6+
# feat - New feature
7+
# fix - Bug fix
8+
# docs - Documentation changes
9+
# style - Formatting, missing semicolons, etc
10+
# refactor - Code refactoring
11+
# perf - Performance improvements
12+
# test - Adding or updating tests
13+
# chore - Build process, dependencies, etc
14+
#
15+
# Scope: optional, describes area of change (e.g., fetch_python_doc)
16+
#
17+
# Subject: brief description (imperative mood, no period)
18+
19+
# Body (separated by blank line):
20+
# - Explain WHAT and WHY (not HOW)
21+
# - Wrap at 72 characters
22+
# - Use bullet points for multiple changes
23+
24+
# Footer (optional):
25+
# - Reference issues: Closes #123, Fixes #456
26+
# - Breaking changes: BREAKING CHANGE: description
27+
28+
# Example:
29+
# feat(fetch_python_doc): add offset/limit pagination
30+
#
31+
# Add offset and limit parameters to enable windowing of large
32+
# documentation responses. This allows agents to lazy load content
33+
# in chunks while respecting context caps.
34+
#
35+
# - Add offset parameter (default: 0) for character offset
36+
# - Add limit parameter (default: 12000) for max characters
37+
# - Update formatDocument() to window content with progress indicators
38+
# - Document lazy loading usage patterns in README

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Yago Riveiro
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# opencode-python-docs
2+
3+
OpenCode plugin for Python documentation lookup via DevDocs.
4+
5+
## Quick Start
6+
7+
Add to `~/.config/opencode/opencode.json`:
8+
9+
```json
10+
{ "plugin": ["opencode-python-docs"] }
11+
```
12+
13+
## Features
14+
15+
- **Search** Python stdlib, language reference, tutorials, and more
16+
- **Fetch** full documentation as clean Markdown
17+
- **Cache** with intelligent TTL-based garbage collection
18+
- **Multiple versions** supported: 3.14, 3.13, 3.12, 3.11, 3.10, 3.9
19+
20+
## Tools
21+
22+
### `python_docs`
23+
24+
Search Python documentation index.
25+
26+
| Argument | Type | Description |
27+
| ---------- | ------ | ------------- |
28+
| `query` | string | Search query (e.g., 'asyncio', 'pathlib') |
29+
| `version` | string? | Python version (default: 3.14) |
30+
| `type` | string? | Filter by doc type |
31+
| `limit` | number? | Max results (default: 20) |
32+
33+
**Example:**
34+
35+
```text
36+
python_docs query="asyncio" version="3.12"
37+
```
38+
39+
### `fetch_python_doc`
40+
41+
Fetch full documentation as Markdown.
42+
43+
| Argument | Type | Description |
44+
| ---------- | ------ | ------------- |
45+
| `path` | string | Doc path from search results |
46+
| `version` | string? | Python version (default: 3.14) |
47+
| `anchor` | string? | Jump to specific section by anchor ID |
48+
| `offset` | number? | Character offset for pagination (default: 0) |
49+
| `limit` | number? | Max characters to return (default: 12000) |
50+
51+
**Example:**
52+
53+
```text
54+
fetch_python_doc path="library/asyncio"
55+
```
56+
57+
**Pagination example:**
58+
59+
```text
60+
# First chunk
61+
fetch_python_doc path="library/asyncio" offset=0 limit=5000
62+
63+
# Continue reading
64+
fetch_python_doc path="library/asyncio" offset=5000 limit=5000
65+
```
66+
67+
## Caching
68+
69+
- **Index cache**: 24 hours TTL
70+
- **Doc cache**: 7 days TTL
71+
- **Location**: `~/.cache/opencode/python-docs/`
72+
- **Garbage collection**: Runs on startup and server reconnect
73+
74+
## Development
75+
76+
```bash
77+
git clone https://github.com/yriveiro/opencode-python-docs
78+
cd opencode-python-docs
79+
bun install
80+
bun run build
81+
```
82+
83+
### Scripts
84+
85+
| Command | Description |
86+
| --------- | ------------- |
87+
| `bun run build` | Build the plugin |
88+
| `bun run typecheck` | Run TypeScript type checking |
89+
| `bun run test` | Run tests |
90+
| `bun run format` | Format code with Biome |
91+
| `bun run lint` | Run Biome linter |
92+
| `bun run check` | Run all checks (lint + format) |
93+
94+
## License
95+
96+
MIT

‎biome.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
3+
"vcs": {
4+
"enabled": true,
5+
"clientKind": "git",
6+
"useIgnoreFile": true
7+
},
8+
"files": {
9+
"ignoreUnknown": false,
10+
"includes": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.json"]
11+
},
12+
"formatter": {
13+
"enabled": true,
14+
"indentStyle": "space",
15+
"lineWidth": 100
16+
},
17+
"linter": {
18+
"enabled": true,
19+
"rules": {
20+
"recommended": true,
21+
"suspicious": {
22+
"noExplicitAny": "off"
23+
}
24+
}
25+
},
26+
"javascript": {
27+
"formatter": {
28+
"quoteStyle": "double"
29+
}
30+
},
31+
"assist": {
32+
"enabled": true,
33+
"actions": {
34+
"source": {
35+
"organizeImports": {
36+
"level": "on"
37+
}
38+
}
39+
}
40+
}
41+
}

‎bun.lock‎

Lines changed: 63 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)