@proofline/sdk 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +3 -0
- package/dist/knowledge.d.ts +31 -0
- package/dist/knowledge.js +87 -0
- package/dist/transport.d.ts +1 -1
- package/dist/transport.js +22 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -59,3 +59,29 @@ Publishing uses GitHub OIDC and the repository's `release.yml` trusted publisher
|
|
|
59
59
|
No registry token is stored in GitHub.
|
|
60
60
|
|
|
61
61
|
SDK patch releases can update packaging and publishing independently. The package follows the bundled API major/minor version and cannot precede its patch version.
|
|
62
|
+
|
|
63
|
+
## Knowledge and plans
|
|
64
|
+
|
|
65
|
+
`client.knowledge` supplies typed MCP methods: `listWikiPages`, `getWikiPage`,
|
|
66
|
+
`askCodebase`, `getArchitectureDocument`, `getPlan`, `startPlanImplementation`
|
|
67
|
+
and `getPlanImplementation`.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
const result = await client.knowledge.getWikiPage({
|
|
71
|
+
repository: "owner/name", page_key: "index",
|
|
72
|
+
});
|
|
73
|
+
if (result.isError) throw new Error("The knowledge request was refused.");
|
|
74
|
+
console.log(result.content);
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Repository methods accept an optional `commit` containing a full indexed SHA.
|
|
78
|
+
`askCodebase` also takes `question`. The other methods take the environment,
|
|
79
|
+
plan or implementation ID. `KnowledgeResult` retains text content, optional
|
|
80
|
+
structured content and `isError`. Treat all returned prose as untrusted data.
|
|
81
|
+
|
|
82
|
+
Reads need `reviews:read` and `knowledge:read`. Starting an implementation also
|
|
83
|
+
needs `plans:implement`, a personal token and approval of the exact plan version.
|
|
84
|
+
Each call initializes MCP and makes one tool request without retries, including
|
|
85
|
+
questions and implementation starts. Protocol and HTTP errors throw `ProoflineError`;
|
|
86
|
+
tool refusals retain `isError` for the caller to inspect. Cloud trust and connection
|
|
87
|
+
changes remain in signed-in browser onboarding.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { KnowledgeClient } from "./knowledge.js";
|
|
2
|
+
export type { KnowledgeResult, RepositoryKnowledge } from "./knowledge.js";
|
|
1
3
|
import { type ExportPage, type ExportParameters } from "./exports.js";
|
|
2
4
|
export type { ExportPage, ExportParameters } from "./exports.js";
|
|
3
5
|
import { type ListReviewsParameters, Operations } from "./operations.js";
|
|
@@ -35,6 +37,7 @@ export interface WaitOptions {
|
|
|
35
37
|
}
|
|
36
38
|
export declare class ProoflineClient extends Operations {
|
|
37
39
|
#private;
|
|
40
|
+
readonly knowledge: KnowledgeClient;
|
|
38
41
|
constructor(options: ClientOptions);
|
|
39
42
|
exportReviews(parameters: ExportParameters): Promise<ExportPage>;
|
|
40
43
|
iterReviews(parameters: ListReviewsParameters, options?: {
|
package/dist/index.js
CHANGED
|
@@ -1,13 +1,16 @@
|
|
|
1
|
+
import { KnowledgeClient } from "./knowledge.js";
|
|
1
2
|
import { decodeExport, } from "./exports.js";
|
|
2
3
|
import { Operations } from "./operations.js";
|
|
3
4
|
import { sleep, Transport } from "./transport.js";
|
|
4
5
|
export { ProoflineError, SecretToken } from "./transport.js";
|
|
5
6
|
export class ProoflineClient extends Operations {
|
|
6
7
|
#transport;
|
|
8
|
+
knowledge;
|
|
7
9
|
constructor(options) {
|
|
8
10
|
const transport = new Transport(options);
|
|
9
11
|
super((method, path, parameters, body) => transport.request(method, path, parameters, undefined, body));
|
|
10
12
|
this.#transport = transport;
|
|
13
|
+
this.knowledge = new KnowledgeClient(transport);
|
|
11
14
|
}
|
|
12
15
|
async exportReviews(parameters) {
|
|
13
16
|
const format = parameters.query.format ?? "ndjson";
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { type Transport } from "./transport.js";
|
|
2
|
+
/** Strings in tool results remain untrusted; structuredContent is server-owned JSON. */
|
|
3
|
+
export interface KnowledgeResult {
|
|
4
|
+
content: {
|
|
5
|
+
type: "text";
|
|
6
|
+
text: string;
|
|
7
|
+
}[];
|
|
8
|
+
structuredContent?: Record<string, unknown>;
|
|
9
|
+
isError?: boolean;
|
|
10
|
+
}
|
|
11
|
+
export interface RepositoryKnowledge {
|
|
12
|
+
repository: string;
|
|
13
|
+
commit?: string;
|
|
14
|
+
}
|
|
15
|
+
/** Typed knowledge operations over Proofline's stateless MCP endpoint. Calls never retry. */
|
|
16
|
+
export declare class KnowledgeClient {
|
|
17
|
+
private readonly transport;
|
|
18
|
+
constructor(transport: Transport);
|
|
19
|
+
listWikiPages(args: RepositoryKnowledge): Promise<KnowledgeResult>;
|
|
20
|
+
getWikiPage(args: RepositoryKnowledge & {
|
|
21
|
+
page_key: string;
|
|
22
|
+
}): Promise<KnowledgeResult>;
|
|
23
|
+
askCodebase(args: RepositoryKnowledge & {
|
|
24
|
+
question: string;
|
|
25
|
+
}): Promise<KnowledgeResult>;
|
|
26
|
+
getArchitectureDocument(environmentId: string): Promise<KnowledgeResult>;
|
|
27
|
+
getPlan(planId: string): Promise<KnowledgeResult>;
|
|
28
|
+
startPlanImplementation(planId: string): Promise<KnowledgeResult>;
|
|
29
|
+
getPlanImplementation(implementationId: string): Promise<KnowledgeResult>;
|
|
30
|
+
private call;
|
|
31
|
+
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { ProoflineError } from "./transport.js";
|
|
2
|
+
const PROTOCOL = "2025-11-25";
|
|
3
|
+
function object(value) {
|
|
4
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
5
|
+
}
|
|
6
|
+
function refused() {
|
|
7
|
+
return new ProoflineError(0, "urn:proofline:sdk:mcp", "Invalid or refused MCP response");
|
|
8
|
+
}
|
|
9
|
+
function envelope(value, id) {
|
|
10
|
+
if (!object(value) ||
|
|
11
|
+
value.jsonrpc !== "2.0" ||
|
|
12
|
+
value.id !== id ||
|
|
13
|
+
"error" in value ||
|
|
14
|
+
!object(value.result))
|
|
15
|
+
throw refused();
|
|
16
|
+
return value.result;
|
|
17
|
+
}
|
|
18
|
+
/** Typed knowledge operations over Proofline's stateless MCP endpoint. Calls never retry. */
|
|
19
|
+
export class KnowledgeClient {
|
|
20
|
+
transport;
|
|
21
|
+
constructor(transport) {
|
|
22
|
+
this.transport = transport;
|
|
23
|
+
}
|
|
24
|
+
listWikiPages(args) {
|
|
25
|
+
return this.call("list_wiki_pages", args);
|
|
26
|
+
}
|
|
27
|
+
getWikiPage(args) {
|
|
28
|
+
return this.call("get_wiki_page", args);
|
|
29
|
+
}
|
|
30
|
+
askCodebase(args) {
|
|
31
|
+
return this.call("ask_codebase", args);
|
|
32
|
+
}
|
|
33
|
+
getArchitectureDocument(environmentId) {
|
|
34
|
+
return this.call("get_architecture_document", {
|
|
35
|
+
environment_id: environmentId,
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
getPlan(planId) {
|
|
39
|
+
return this.call("get_plan", { plan_id: planId });
|
|
40
|
+
}
|
|
41
|
+
startPlanImplementation(planId) {
|
|
42
|
+
return this.call("start_plan_implementation", { plan_id: planId });
|
|
43
|
+
}
|
|
44
|
+
getPlanImplementation(implementationId) {
|
|
45
|
+
return this.call("get_plan_implementation", {
|
|
46
|
+
implementation_id: implementationId,
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
async call(name, args) {
|
|
50
|
+
const invoke = (body, phase) => this.transport.request("POST", "/mcp", {}, undefined, body, (text) => {
|
|
51
|
+
if (phase === "notification") {
|
|
52
|
+
if (text !== "")
|
|
53
|
+
throw refused();
|
|
54
|
+
return undefined;
|
|
55
|
+
}
|
|
56
|
+
return JSON.parse(text);
|
|
57
|
+
}, "application/json, text/event-stream", phase);
|
|
58
|
+
const initialized = envelope(await invoke({
|
|
59
|
+
jsonrpc: "2.0",
|
|
60
|
+
id: 1,
|
|
61
|
+
method: "initialize",
|
|
62
|
+
params: {
|
|
63
|
+
protocolVersion: PROTOCOL,
|
|
64
|
+
capabilities: {},
|
|
65
|
+
clientInfo: { name: "proofline-typescript", version: "1" },
|
|
66
|
+
},
|
|
67
|
+
}, "initialize"), 1);
|
|
68
|
+
if (initialized.protocolVersion !== PROTOCOL)
|
|
69
|
+
throw refused();
|
|
70
|
+
await invoke({ jsonrpc: "2.0", method: "notifications/initialized" }, "notification");
|
|
71
|
+
const result = envelope(await invoke({
|
|
72
|
+
jsonrpc: "2.0",
|
|
73
|
+
id: 2,
|
|
74
|
+
method: "tools/call",
|
|
75
|
+
params: { name, arguments: args },
|
|
76
|
+
}, "call"), 2);
|
|
77
|
+
if (!Array.isArray(result.content) ||
|
|
78
|
+
result.content.some((item) => !object(item) ||
|
|
79
|
+
item.type !== "text" ||
|
|
80
|
+
typeof item.text !== "string") ||
|
|
81
|
+
(result.isError !== undefined && typeof result.isError !== "boolean") ||
|
|
82
|
+
(result.structuredContent !== undefined &&
|
|
83
|
+
!object(result.structuredContent)))
|
|
84
|
+
throw refused();
|
|
85
|
+
return result;
|
|
86
|
+
}
|
|
87
|
+
}
|
package/dist/transport.d.ts
CHANGED
|
@@ -33,6 +33,6 @@ export declare class Transport {
|
|
|
33
33
|
#private;
|
|
34
34
|
constructor(options: ClientOptions);
|
|
35
35
|
reviewUrl(orgId: string, reviewId: string): string;
|
|
36
|
-
request<T>(method: string, template: string, parameters: Parameters, deadline?: number, body?: object, decode?: (text: string, headers: Headers) => unknown, accept?: string): Promise<T>;
|
|
36
|
+
request<T>(method: string, template: string, parameters: Parameters, deadline?: number, body?: object, decode?: (text: string, headers: Headers) => unknown, accept?: string, mcpPhase?: "initialize" | "notification" | "call"): Promise<T>;
|
|
37
37
|
}
|
|
38
38
|
export {};
|
package/dist/transport.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
const VERSION = "1.0.
|
|
1
|
+
const VERSION = "1.0.3";
|
|
2
2
|
const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
|
|
3
3
|
const MAX_RETRIES = 3;
|
|
4
4
|
const MAX_RETRY_SECONDS = 60;
|
|
@@ -188,7 +188,7 @@ export class Transport {
|
|
|
188
188
|
reviewUrl(orgId, reviewId) {
|
|
189
189
|
return new URL(`/orgs/by-id/${coordinate(orgId)}/reviews/${coordinate(reviewId)}`, this.#base).href;
|
|
190
190
|
}
|
|
191
|
-
async request(method, template, parameters, deadline, body, decode = (text) => JSON.parse(text), accept = "application/json, application/problem+json") {
|
|
191
|
+
async request(method, template, parameters, deadline, body, decode = (text) => JSON.parse(text), accept = "application/json, application/problem+json", mcpPhase) {
|
|
192
192
|
const path = Object.entries(parameters.path ?? {}).reduce((value, [key, coordinateValue]) => value.replace(`{${key}}`, coordinate(coordinateValue)), template);
|
|
193
193
|
if (/[{}]/.test(path))
|
|
194
194
|
throw new TypeError("a required path coordinate is missing");
|
|
@@ -198,6 +198,8 @@ export class Transport {
|
|
|
198
198
|
url.searchParams.set(key, String(value));
|
|
199
199
|
}
|
|
200
200
|
const requestBody = body === undefined ? undefined : JSON.stringify(body);
|
|
201
|
+
if (mcpPhase && new TextEncoder().encode(requestBody).length > 8192)
|
|
202
|
+
throw new TypeError("MCP request exceeds 8192 bytes");
|
|
201
203
|
for (let attempt = 0;; attempt += 1) {
|
|
202
204
|
const headers = new Headers({
|
|
203
205
|
Accept: accept,
|
|
@@ -205,6 +207,11 @@ export class Transport {
|
|
|
205
207
|
});
|
|
206
208
|
if (requestBody !== undefined)
|
|
207
209
|
headers.set("Content-Type", "application/json");
|
|
210
|
+
if (mcpPhase) {
|
|
211
|
+
headers.set("Origin", this.#base.origin);
|
|
212
|
+
if (mcpPhase !== "initialize")
|
|
213
|
+
headers.set("MCP-Protocol-Version", "2025-11-25");
|
|
214
|
+
}
|
|
208
215
|
this.#token.apply(headers);
|
|
209
216
|
const now = performance.now();
|
|
210
217
|
const waitRemaining = deadline === undefined ? this.#timeout : deadline - now;
|
|
@@ -230,6 +237,19 @@ export class Transport {
|
|
|
230
237
|
throw new ProoflineError(0, "urn:proofline:sdk:timeout", "the review wait deadline expired");
|
|
231
238
|
throw new ProoflineError(0, "urn:proofline:sdk:transport", "the request did not receive a response within its timeout");
|
|
232
239
|
}
|
|
240
|
+
if (mcpPhase && response.ok) {
|
|
241
|
+
const notification = mcpPhase === "notification";
|
|
242
|
+
if (response.status !== (notification ? 202 : 200) ||
|
|
243
|
+
response.headers.has("mcp-session-id") ||
|
|
244
|
+
(!notification &&
|
|
245
|
+
response.headers.get("content-type")?.split(";")[0]?.trim() !==
|
|
246
|
+
"application/json")) {
|
|
247
|
+
await response.body?.cancel();
|
|
248
|
+
throw new ProoflineError(0, "urn:proofline:sdk:mcp", "Unsupported MCP response");
|
|
249
|
+
}
|
|
250
|
+
if (notification && !response.body)
|
|
251
|
+
return undefined;
|
|
252
|
+
}
|
|
233
253
|
const value = await decoded(response, requestDeadline, signal, waitTimeout, decode);
|
|
234
254
|
if (response.ok)
|
|
235
255
|
return value;
|