Skip to content

Commit 471b910

Browse files
devm33devm33
committed
Update readme
1 parent 0294f84 commit 471b910

File tree

1 file changed

+307
-1
lines changed

1 file changed

+307
-1
lines changed

‎README.md‎

Lines changed: 307 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,307 @@
1-
# copilot-language-server-release
1+
# @github/copilot-language-server
2+
3+
The Copilot Language Server enables any editor or IDE to integrate with GitHub
4+
Copilot via [the language server protocol](https://microsoft.github.io/language-server-protocol/).
5+
6+
**[GitHub Copilot](https://github.com/features/copilot)** is an AI pair programmer tool that helps you write code faster and smarter.
7+
8+
**Sign up for [GitHub Copilot Free](https://github.com/settings/copilot)!**
9+
10+
## Getting Started
11+
12+
To integrate with the Copilot Language Server, download the latest release from npm:
13+
14+
```sh
15+
npm install @github/copilot-language-server
16+
```
17+
18+
To run the language server, platform-specific binaries are available in the `native` directory of the npm package. For
19+
example, for macOS on arm64:
20+
21+
```sh
22+
./node_modules/@github/copilot-language-server/native/darwin-arm64/copilot-language-server --version
23+
```
24+
25+
Or you can use [Node.js](https://nodejs.org/en/download/) version 20.x or later:
26+
27+
```sh
28+
node ./node_modules/@github/copilot-language-server/dist/language-server.js --version
29+
```
30+
31+
If using the `language-server.js` distribution, it is necessary to retain the entire `dist` directory contents.
32+
33+
34+
## Communication Protocol
35+
36+
[LSP (Language Server Protocol)](https://microsoft.github.io/language-server-protocol/) is used to communicate
37+
with the client. The base protocol is [JSON-RPC 2.0 with additional
38+
headers](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#baseProtocol).
39+
40+
The Copilot Language Server attempts to follow the LSP spec as closely as possible, but many custom messages are
41+
employed to support the unique features of Copilot.
42+
43+
## Initialization
44+
45+
Per the LSP spec, the client is expected to send a
46+
[`initialize`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initialize)
47+
request to the language server as a first message. Example parameters:
48+
49+
```json
50+
{
51+
"processId": 1234,
52+
"workspaceFolders": [
53+
{
54+
"uri": "file:///home/user/project"
55+
}
56+
],
57+
"capabilities": {
58+
"workspace": {"workspaceFolders": true}
59+
},
60+
"initializationOptions": {
61+
"editorInfo": {
62+
"name": "GNU ed",
63+
"version": "1.19"
64+
},
65+
"editorPluginInfo": {
66+
"name": "GitHub Copilot for ed",
67+
"version": "1.0.0"
68+
}
69+
}
70+
}
71+
```
72+
73+
After receiving the response to `initialize`, the second message the client must send is an
74+
[`initialized`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initialized)
75+
notification.
76+
77+
## Configuration Management
78+
79+
After initialization, clients should send a
80+
[`workspace/didChangeConfiguration`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_didChangeConfiguration)
81+
notification to inform the language server about the initial configuration, and again each time the configuration
82+
changes. Example parameters:
83+
84+
```json
85+
{
86+
"settings": {
87+
"http": {
88+
"proxy": "http://localhost:8888",
89+
"proxyStrictSSL": true,
90+
"proxyKerberosServicePrincipal": "spn"
91+
},
92+
"telemetry": {
93+
"telemetryLevel": "all"
94+
},
95+
"github-enterprise": {
96+
"uri": "https://example.ghe.com"
97+
}
98+
}
99+
}
100+
```
101+
102+
Pull based configuration on
103+
[`workspace/configuration`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_configuration)
104+
is also supported.
105+
106+
## Workspace Folders Synchronization
107+
108+
Workspace folders are optional but highly recommended as they greatly improve the quality of suggestions. See the LSP spec for
109+
[`workspace/didChangeWorkspaceFolders`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_didChangeWorkspaceFolders).
110+
111+
## Text Document Synchronization
112+
113+
Per the LSP spec for
114+
[text document synchronization](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_synchronization),
115+
support for `textDocument/didOpen`, `textDocument/didChange`, and `textDocument/didClose` is required, using incremental
116+
sync.
117+
118+
## Text Document Focusing
119+
120+
Additionally a custom `textDocument/didFocus` notification should be sent when the client focuses another document
121+
(e.g., changing tabs). Example parameters:
122+
123+
```json
124+
{
125+
"textDocument": {
126+
"uri": "file:///path/to/file"
127+
}
128+
}
129+
```
130+
131+
If no document is focused, a request with no parameters (`{}`) may be sent.
132+
133+
## Status Notification
134+
135+
The status is sent to the client as a `didChangeStatus` notification. Typically this would be conveyed to the user in a
136+
status bar icon or other UI affordance.
137+
138+
Notification includes the following fields:
139+
140+
- `message` - a string describing the status (can be empty)
141+
- `kind` - status of the language server:
142+
- `'Normal'` - When everything is working normally.
143+
- `'Error'` - When not authorized and authenticated.
144+
- `'Warning'` - When there is a temporary issue, such as a failed HTTP request.
145+
- `'Inactive'` - When the current file is ignored due to file size or content exclusions.
146+
147+
## Authentication
148+
149+
To sign in, call `signIn`. This will return a response like the following:
150+
151+
```json
152+
{
153+
"userCode": "ABCD-EFGH",
154+
"command": {
155+
"command": "github.copilot.finishDeviceFlow",
156+
"arguments": [],
157+
"title": "Sign in"
158+
}
159+
}
160+
```
161+
162+
Instruct the user to copy the `userCode` to their clipboard (and/or copy it programmatically). When the user is ready, invoke
163+
[`workspace/executeCommand`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_executeCommand)
164+
to execute the `command`. This will open a browser window that walks the user through the authentication process.
165+
Shortly (up to 10 seconds) after the user finishes signing in, you should see a status notification reflecting the new
166+
state.
167+
168+
If available, the language server will use
169+
[`window/showDocument`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#window_showDocument)
170+
to open the URL. Otherwise, it will attempt to open the URL natively (e.g., with `/usr/bin/open` on macOS).
171+
172+
To sign out, call `signOut`.
173+
174+
## Inline Completions
175+
176+
The [`textDocument/inlineCompletion`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_inlineCompletion)
177+
request from the draft version of the next LSP spec is used to retrieve inline ("ghost text") completions, with some
178+
non-standard additions (`textDocument.version` and `formattingOptions`) to the parameters:
179+
180+
```json
181+
{
182+
"textDocument": {
183+
"uri": "file:///path/to/file",
184+
"version": 0
185+
},
186+
"position": {"line": 1, "character": 2},
187+
"context": {
188+
"triggerKind": 2
189+
},
190+
"formattingOptions": {
191+
"tabSize": 4,
192+
"insertSpaces": true
193+
}
194+
}
195+
```
196+
197+
The result is an object containing an `items` array.
198+
199+
```json
200+
{
201+
"items": [
202+
{
203+
"insertText": "a helpful suggestion",
204+
"range": {
205+
"start": {"line": 1, "character": 0},
206+
"end": {"line": 1, "character": 2}
207+
},
208+
"command": {
209+
"command": "github.copilot.didAcceptCompletionItem",
210+
"arguments": ["some id"]
211+
}
212+
}
213+
]
214+
}
215+
```
216+
217+
Newlines in `insertText` should be normalized as is appropriate for the editor before inserting into the document.
218+
219+
The `command` field, per the LSP spec, is called via
220+
[`workspace/executeCommand`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_executeCommand)
221+
*after* the user accepts the completion. Copilot uses this for acceptance telemetry.
222+
223+
The LSP spec does not provide an event for showing the completion, so a custom `textDocument/didShowCompletion` is used.
224+
Call it with an `item` parameter containing the full completion item:
225+
226+
```json
227+
{
228+
"item": {
229+
"insertText": "a helpful suggestion",
230+
"range": {
231+
"start": {"line": 1, "character": 0},
232+
"end": {"line": 1, "character": 2}
233+
},
234+
"command": {
235+
"command": "github.copilot.didAcceptCompletionItem",
236+
"arguments": ["some id"]
237+
}
238+
}
239+
}
240+
```
241+
242+
Similarly, for partial acceptance, send a `textDocument/didPartiallyAcceptCompletion` notification with the full
243+
item, plus the length (in UTF-16 codepoints) of the completion that was accepted:
244+
245+
```json
246+
{
247+
"item": {
248+
"insertText": "a helpful suggestion",
249+
"range": {
250+
"start": {"line": 1, "character": 0},
251+
"end": {"line": 1, "character": 2}
252+
},
253+
"command": {
254+
"command": "github.copilot.didAcceptCompletionItem",
255+
"arguments": ["some id"]
256+
}
257+
},
258+
"acceptedLength": 9
259+
}
260+
```
261+
262+
Note that the `acceptedLength` includes everything from the start of `insertText` to the end of the accepted text. It is
263+
*not* the length of the accepted text itself.
264+
265+
## Panel Completions
266+
267+
Panel completions are used for "Open Copilot" style completions. They are similar to inline completions, but are shown
268+
in a separate panel. They are retrieved using the custom `textDocument/copilotPanelCompletion` request, which has
269+
parameters closely modeled after `textDocument/inlineCompletion`:
270+
271+
```json
272+
{
273+
"textDocument": {
274+
"uri": "file:///path/to/file",
275+
"version": 0
276+
},
277+
"position": {"line": 1, "character": 2},
278+
"partialResultToken": "some token"
279+
}
280+
```
281+
282+
If provided, the `partialResultToken` is used to stream
283+
[partial results](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#partialResults)
284+
back to the client. Both the return type and the partial result type are the same as for inline completions: an object
285+
containing an `items` array. These items have the same `command` that must be invoked with `workspace/executeCommand`
286+
after accepting to trigger acceptance telemetry. Partial acceptance and shown events are not supported here.
287+
288+
## Cancellation
289+
290+
`textDocument/inlineCompletion` supports cancel-previous strategy for cancellation: If you send new completions
291+
request, the previous request is cancelled.
292+
293+
Additionally the LSP `$/cancelRequest` method is supported to cancel any request. It is strongly encouraged to eagerly
294+
cancel completion requests as soon as possible.
295+
296+
## Logs
297+
298+
Logs are sent to the client as
299+
[`window/logMessage`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#window_logMessage)
300+
notifications.
301+
302+
## Messages
303+
304+
The client may be sent
305+
[`window/showMessageRequest`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#window_showMessage)
306+
requests. Support for these messages is essential as they are used for important notifications including account and
307+
billing.

0 commit comments

Comments
 (0)