metergraph 0.3.2 → 0.5.0
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 +44 -2
- package/dist/batch-first.d.ts +112 -0
- package/dist/batch-first.js +207 -0
- package/dist/capture.d.ts +2 -0
- package/dist/capture.js +10 -4
- package/dist/index.d.ts +10 -0
- package/dist/index.js +24 -1
- package/dist/provider-batch.d.ts +160 -0
- package/dist/provider-batch.js +240 -0
- package/dist/repo-config.d.ts +22 -0
- package/dist/repo-config.js +214 -0
- package/dist/session.d.ts +23 -0
- package/dist/session.js +109 -0
- package/dist/transport.d.ts +3 -0
- package/dist/transport.js +13 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The narrow adapter boundary batchFirst() drives, plus a worker-only OpenAI
|
|
3
|
+
* Batch API implementation. Deliberately duck-typed against the openai
|
|
4
|
+
* package's shape (see OpenAIBatchCapableClient) rather than importing it —
|
|
5
|
+
* `openai` is an optional peer dependency of this package, and structural
|
|
6
|
+
* typing already lets a real `OpenAI` client instance satisfy this
|
|
7
|
+
* interface without any import, type-only or otherwise.
|
|
8
|
+
*
|
|
9
|
+
* Every method here returns only bounded, structural information — a
|
|
10
|
+
* status, a result the caller explicitly asked for, and a boolean noting
|
|
11
|
+
* whether that result happened to contain a tool-call plan. No adapter
|
|
12
|
+
* method inspects or logs a provider error body, a credential, or a raw
|
|
13
|
+
* prompt.
|
|
14
|
+
*/
|
|
15
|
+
/** A caller's own provider request body (e.g. an OpenAI Responses payload).
|
|
16
|
+
* Only `stream` and `tools` are inspected by this module; every other
|
|
17
|
+
* field passes through untouched. */
|
|
18
|
+
export type BatchFirstRequest = Record<string, unknown> & {
|
|
19
|
+
stream?: boolean;
|
|
20
|
+
tools?: unknown[];
|
|
21
|
+
};
|
|
22
|
+
export interface BatchHandle {
|
|
23
|
+
/** The provider's own batch identifier — never returned to a caller of
|
|
24
|
+
* batchFirst() or logged; adapters use it only to poll/read their own
|
|
25
|
+
* batch. */
|
|
26
|
+
providerBatchId: string;
|
|
27
|
+
}
|
|
28
|
+
export type BatchPollStatus = "pending" | "completed" | "failed" | "expired";
|
|
29
|
+
export interface BatchPollResult {
|
|
30
|
+
status: BatchPollStatus;
|
|
31
|
+
}
|
|
32
|
+
export interface ProviderBatchResult<TResult = unknown> {
|
|
33
|
+
result: TResult;
|
|
34
|
+
/** Whether this result's own output happens to include a tool/function
|
|
35
|
+
* call — reported as a boolean only, never by exposing the call's
|
|
36
|
+
* arguments or the surrounding response through this flag. */
|
|
37
|
+
containedToolCallPlan: boolean;
|
|
38
|
+
}
|
|
39
|
+
export interface ProviderBatchEligibility {
|
|
40
|
+
eligible: boolean;
|
|
41
|
+
reason?: string;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The seam batchFirst() is written against. An adapter submits exactly one
|
|
45
|
+
* request per batch and knows how to poll it, read its terminal result,
|
|
46
|
+
* and run the same request directly (bypassing batch entirely) as a
|
|
47
|
+
* fallback.
|
|
48
|
+
*/
|
|
49
|
+
export interface ProviderBatchAdapter<TResult = unknown> {
|
|
50
|
+
eligibility(request: BatchFirstRequest): ProviderBatchEligibility;
|
|
51
|
+
submitOne(request: BatchFirstRequest): Promise<BatchHandle>;
|
|
52
|
+
poll(handle: BatchHandle): Promise<BatchPollResult>;
|
|
53
|
+
readResult(handle: BatchHandle): Promise<ProviderBatchResult<TResult>>;
|
|
54
|
+
direct(request: BatchFirstRequest): Promise<ProviderBatchResult<TResult>>;
|
|
55
|
+
}
|
|
56
|
+
/** The minimal slice of the `openai` package's client shape this adapter
|
|
57
|
+
* calls. A real `OpenAI` client instance satisfies this structurally. */
|
|
58
|
+
export interface OpenAIBatchCapableClient {
|
|
59
|
+
files: {
|
|
60
|
+
create(params: {
|
|
61
|
+
file: Blob;
|
|
62
|
+
purpose: string;
|
|
63
|
+
}): Promise<{
|
|
64
|
+
id: string;
|
|
65
|
+
}>;
|
|
66
|
+
content(fileId: string): Promise<{
|
|
67
|
+
text(): Promise<string>;
|
|
68
|
+
}>;
|
|
69
|
+
};
|
|
70
|
+
batches: {
|
|
71
|
+
create(params: {
|
|
72
|
+
input_file_id: string;
|
|
73
|
+
endpoint: string;
|
|
74
|
+
completion_window: string;
|
|
75
|
+
}): Promise<{
|
|
76
|
+
id: string;
|
|
77
|
+
status?: string;
|
|
78
|
+
}>;
|
|
79
|
+
retrieve(batchId: string): Promise<{
|
|
80
|
+
id: string;
|
|
81
|
+
status?: string;
|
|
82
|
+
output_file_id?: string | null;
|
|
83
|
+
}>;
|
|
84
|
+
};
|
|
85
|
+
responses: {
|
|
86
|
+
create(request: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
export declare class ProviderBatchError extends Error {
|
|
90
|
+
}
|
|
91
|
+
export declare function createOpenAIBatchAdapter(client: OpenAIBatchCapableClient): ProviderBatchAdapter;
|
|
92
|
+
/** The minimal slice of the `@anthropic-ai/sdk` package's client shape this
|
|
93
|
+
* adapter calls. A real `Anthropic` client instance satisfies this
|
|
94
|
+
* structurally — see `patchAnthropicBatchResults` in wrap.ts, which
|
|
95
|
+
* confirms `messages.batches.results()` returns an async iterable of
|
|
96
|
+
* `{custom_id, result: {type, message}}` items against the real SDK. */
|
|
97
|
+
export interface AnthropicBatchCapableClient {
|
|
98
|
+
messages: {
|
|
99
|
+
create(request: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
100
|
+
batches: {
|
|
101
|
+
create(params: {
|
|
102
|
+
requests: Array<{
|
|
103
|
+
custom_id: string;
|
|
104
|
+
params: Record<string, unknown>;
|
|
105
|
+
}>;
|
|
106
|
+
}): Promise<{
|
|
107
|
+
id: string;
|
|
108
|
+
processing_status?: string;
|
|
109
|
+
}>;
|
|
110
|
+
retrieve(batchId: string): Promise<{
|
|
111
|
+
id: string;
|
|
112
|
+
processing_status?: string;
|
|
113
|
+
request_counts?: Record<string, number>;
|
|
114
|
+
}>;
|
|
115
|
+
results(batchId: string): AsyncIterable<unknown>;
|
|
116
|
+
};
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
export declare function createAnthropicBatchAdapter(client: AnthropicBatchCapableClient): ProviderBatchAdapter;
|
|
120
|
+
/** The minimal slice of the `@google/genai` package's client shape this
|
|
121
|
+
* adapter calls. A real Google GenAI client instance satisfies this
|
|
122
|
+
* structurally. The exact batch job/response wire shape below (`state` vs
|
|
123
|
+
* `metadata.state`, `dest.inlinedResponses`) is our best-effort reading of
|
|
124
|
+
* the current Gemini Batch API and needs live/gated verification before
|
|
125
|
+
* production use — see this module's caller-facing report for specifics. */
|
|
126
|
+
export interface GoogleBatchCapableClient {
|
|
127
|
+
models: {
|
|
128
|
+
generateContent(request: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
129
|
+
};
|
|
130
|
+
batches: {
|
|
131
|
+
create(params: {
|
|
132
|
+
model: string;
|
|
133
|
+
src: {
|
|
134
|
+
inlinedRequests: Array<Record<string, unknown>>;
|
|
135
|
+
};
|
|
136
|
+
}): Promise<{
|
|
137
|
+
name: string;
|
|
138
|
+
state?: string;
|
|
139
|
+
metadata?: {
|
|
140
|
+
state?: string;
|
|
141
|
+
};
|
|
142
|
+
}>;
|
|
143
|
+
get(params: {
|
|
144
|
+
name: string;
|
|
145
|
+
}): Promise<{
|
|
146
|
+
name: string;
|
|
147
|
+
state?: string;
|
|
148
|
+
metadata?: {
|
|
149
|
+
state?: string;
|
|
150
|
+
};
|
|
151
|
+
dest?: {
|
|
152
|
+
inlinedResponses?: Array<{
|
|
153
|
+
response?: Record<string, unknown>;
|
|
154
|
+
error?: Record<string, unknown>;
|
|
155
|
+
}>;
|
|
156
|
+
};
|
|
157
|
+
}>;
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
export declare function createGoogleBatchAdapter(client: GoogleBatchCapableClient): ProviderBatchAdapter;
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The narrow adapter boundary batchFirst() drives, plus a worker-only OpenAI
|
|
3
|
+
* Batch API implementation. Deliberately duck-typed against the openai
|
|
4
|
+
* package's shape (see OpenAIBatchCapableClient) rather than importing it —
|
|
5
|
+
* `openai` is an optional peer dependency of this package, and structural
|
|
6
|
+
* typing already lets a real `OpenAI` client instance satisfy this
|
|
7
|
+
* interface without any import, type-only or otherwise.
|
|
8
|
+
*
|
|
9
|
+
* Every method here returns only bounded, structural information — a
|
|
10
|
+
* status, a result the caller explicitly asked for, and a boolean noting
|
|
11
|
+
* whether that result happened to contain a tool-call plan. No adapter
|
|
12
|
+
* method inspects or logs a provider error body, a credential, or a raw
|
|
13
|
+
* prompt.
|
|
14
|
+
*/
|
|
15
|
+
const OPENAI_BATCH_ENDPOINT = "/v1/responses";
|
|
16
|
+
const OPENAI_COMPLETION_WINDOW = "24h";
|
|
17
|
+
// "validating" | "in_progress" | "finalizing" | "cancelling" all fall
|
|
18
|
+
// through to "pending" below, alongside any future status OpenAI adds —
|
|
19
|
+
// only a recognized terminal status is ever treated as terminal.
|
|
20
|
+
const OPENAI_FAILED_STATUSES = new Set(["failed", "cancelled"]);
|
|
21
|
+
function get(value, key) {
|
|
22
|
+
return value && typeof value === "object" ? value[key] : undefined;
|
|
23
|
+
}
|
|
24
|
+
function hasFunctionCall(body) {
|
|
25
|
+
const output = get(body, "output");
|
|
26
|
+
if (!Array.isArray(output))
|
|
27
|
+
return false;
|
|
28
|
+
return output.some((item) => get(item, "type") === "function_call");
|
|
29
|
+
}
|
|
30
|
+
function randomCustomId() {
|
|
31
|
+
if (typeof globalThis.crypto?.randomUUID === "function")
|
|
32
|
+
return globalThis.crypto.randomUUID();
|
|
33
|
+
return `batch-first-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
|
|
34
|
+
}
|
|
35
|
+
export class ProviderBatchError extends Error {
|
|
36
|
+
}
|
|
37
|
+
export function createOpenAIBatchAdapter(client) {
|
|
38
|
+
return {
|
|
39
|
+
eligibility(request) {
|
|
40
|
+
if (request.stream === true) {
|
|
41
|
+
return { eligible: false, reason: "streaming requests are direct-only" };
|
|
42
|
+
}
|
|
43
|
+
return { eligible: true };
|
|
44
|
+
},
|
|
45
|
+
async submitOne(request) {
|
|
46
|
+
const customId = randomCustomId();
|
|
47
|
+
const line = JSON.stringify({
|
|
48
|
+
custom_id: customId,
|
|
49
|
+
method: "POST",
|
|
50
|
+
url: OPENAI_BATCH_ENDPOINT,
|
|
51
|
+
body: request,
|
|
52
|
+
});
|
|
53
|
+
const file = new Blob([`${line}\n`], { type: "application/jsonl" });
|
|
54
|
+
const uploaded = await client.files.create({ file, purpose: "batch" });
|
|
55
|
+
const batch = await client.batches.create({
|
|
56
|
+
input_file_id: uploaded.id,
|
|
57
|
+
endpoint: OPENAI_BATCH_ENDPOINT,
|
|
58
|
+
completion_window: OPENAI_COMPLETION_WINDOW,
|
|
59
|
+
});
|
|
60
|
+
const handle = { providerBatchId: batch.id, customId };
|
|
61
|
+
return handle;
|
|
62
|
+
},
|
|
63
|
+
async poll(handle) {
|
|
64
|
+
const batch = await client.batches.retrieve(handle.providerBatchId);
|
|
65
|
+
const status = batch.status ?? "";
|
|
66
|
+
if (status === "completed")
|
|
67
|
+
return { status: "completed" };
|
|
68
|
+
if (status === "expired")
|
|
69
|
+
return { status: "expired" };
|
|
70
|
+
if (OPENAI_FAILED_STATUSES.has(status))
|
|
71
|
+
return { status: "failed" };
|
|
72
|
+
return { status: "pending" };
|
|
73
|
+
},
|
|
74
|
+
async readResult(handle) {
|
|
75
|
+
const openaiHandle = handle;
|
|
76
|
+
const batch = await client.batches.retrieve(handle.providerBatchId);
|
|
77
|
+
const outputFileId = batch.output_file_id;
|
|
78
|
+
if (!outputFileId) {
|
|
79
|
+
throw new ProviderBatchError("openai batch has no output file to read");
|
|
80
|
+
}
|
|
81
|
+
const file = await client.files.content(outputFileId);
|
|
82
|
+
const text = await file.text();
|
|
83
|
+
for (const rawLine of text.split(/\r?\n/)) {
|
|
84
|
+
const line = rawLine.trim();
|
|
85
|
+
if (!line)
|
|
86
|
+
continue;
|
|
87
|
+
let item;
|
|
88
|
+
try {
|
|
89
|
+
item = JSON.parse(line);
|
|
90
|
+
}
|
|
91
|
+
catch {
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
if (get(item, "custom_id") !== openaiHandle.customId)
|
|
95
|
+
continue;
|
|
96
|
+
const response = get(item, "response");
|
|
97
|
+
const statusCode = Number(get(response, "status_code"));
|
|
98
|
+
const body = get(response, "body");
|
|
99
|
+
const error = get(item, "error");
|
|
100
|
+
if (error != null || (Number.isFinite(statusCode) && statusCode >= 400)) {
|
|
101
|
+
// Never surface the provider's own error text — only that this
|
|
102
|
+
// one item failed.
|
|
103
|
+
throw new ProviderBatchError("openai batch item returned an error response");
|
|
104
|
+
}
|
|
105
|
+
return { result: body, containedToolCallPlan: hasFunctionCall(body) };
|
|
106
|
+
}
|
|
107
|
+
throw new ProviderBatchError("openai batch output did not contain our submitted item");
|
|
108
|
+
},
|
|
109
|
+
async direct(request) {
|
|
110
|
+
const response = await client.responses.create(request);
|
|
111
|
+
return { result: response, containedToolCallPlan: hasFunctionCall(response) };
|
|
112
|
+
},
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
function hasToolUse(message) {
|
|
116
|
+
const content = get(message, "content");
|
|
117
|
+
if (!Array.isArray(content))
|
|
118
|
+
return false;
|
|
119
|
+
return content.some((block) => get(block, "type") === "tool_use");
|
|
120
|
+
}
|
|
121
|
+
export function createAnthropicBatchAdapter(client) {
|
|
122
|
+
return {
|
|
123
|
+
eligibility(request) {
|
|
124
|
+
if (request.stream === true) {
|
|
125
|
+
return { eligible: false, reason: "streaming requests are direct-only" };
|
|
126
|
+
}
|
|
127
|
+
return { eligible: true };
|
|
128
|
+
},
|
|
129
|
+
async submitOne(request) {
|
|
130
|
+
const customId = randomCustomId();
|
|
131
|
+
const batch = await client.messages.batches.create({
|
|
132
|
+
requests: [{ custom_id: customId, params: request }],
|
|
133
|
+
});
|
|
134
|
+
const handle = { providerBatchId: batch.id, customId };
|
|
135
|
+
return handle;
|
|
136
|
+
},
|
|
137
|
+
async poll(handle) {
|
|
138
|
+
const batch = await client.messages.batches.retrieve(handle.providerBatchId);
|
|
139
|
+
if (batch.processing_status !== "ended")
|
|
140
|
+
return { status: "pending" };
|
|
141
|
+
// "ended" is itself a terminal signal — there is no un-ending it, so
|
|
142
|
+
// any bucket shape we don't recognize is bounded to "failed" rather
|
|
143
|
+
// than left pending forever.
|
|
144
|
+
const counts = batch.request_counts ?? {};
|
|
145
|
+
if ((counts.succeeded ?? 0) > 0)
|
|
146
|
+
return { status: "completed" };
|
|
147
|
+
if ((counts.expired ?? 0) > 0)
|
|
148
|
+
return { status: "expired" };
|
|
149
|
+
return { status: "failed" };
|
|
150
|
+
},
|
|
151
|
+
async readResult(handle) {
|
|
152
|
+
const anthropicHandle = handle;
|
|
153
|
+
for await (const item of client.messages.batches.results(handle.providerBatchId)) {
|
|
154
|
+
if (get(item, "custom_id") !== anthropicHandle.customId)
|
|
155
|
+
continue;
|
|
156
|
+
const result = get(item, "result");
|
|
157
|
+
if (get(result, "type") !== "succeeded") {
|
|
158
|
+
// Never surface the provider's own error text — only that this
|
|
159
|
+
// one item failed.
|
|
160
|
+
throw new ProviderBatchError("anthropic batch item did not succeed");
|
|
161
|
+
}
|
|
162
|
+
const message = get(result, "message");
|
|
163
|
+
return { result: message, containedToolCallPlan: hasToolUse(message) };
|
|
164
|
+
}
|
|
165
|
+
throw new ProviderBatchError("anthropic batch results did not contain our submitted item");
|
|
166
|
+
},
|
|
167
|
+
async direct(request) {
|
|
168
|
+
const response = await client.messages.create(request);
|
|
169
|
+
return { result: response, containedToolCallPlan: hasToolUse(response) };
|
|
170
|
+
},
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
const GOOGLE_TERMINAL_STATUS = {
|
|
174
|
+
JOB_STATE_SUCCEEDED: "completed",
|
|
175
|
+
JOB_STATE_FAILED: "failed",
|
|
176
|
+
JOB_STATE_CANCELLED: "failed",
|
|
177
|
+
JOB_STATE_EXPIRED: "expired",
|
|
178
|
+
};
|
|
179
|
+
function hasFunctionCallPart(response) {
|
|
180
|
+
const candidates = get(response, "candidates");
|
|
181
|
+
if (!Array.isArray(candidates))
|
|
182
|
+
return false;
|
|
183
|
+
return candidates.some((candidate) => {
|
|
184
|
+
const parts = get(get(candidate, "content"), "parts");
|
|
185
|
+
if (!Array.isArray(parts))
|
|
186
|
+
return false;
|
|
187
|
+
return parts.some((part) => get(part, "functionCall") != null || get(part, "function_call") != null);
|
|
188
|
+
});
|
|
189
|
+
}
|
|
190
|
+
export function createGoogleBatchAdapter(client) {
|
|
191
|
+
return {
|
|
192
|
+
eligibility(request) {
|
|
193
|
+
if (request.stream === true) {
|
|
194
|
+
return { eligible: false, reason: "streaming requests are direct-only" };
|
|
195
|
+
}
|
|
196
|
+
return { eligible: true };
|
|
197
|
+
},
|
|
198
|
+
async submitOne(request) {
|
|
199
|
+
const { model, ...inlineRequest } = request;
|
|
200
|
+
if (typeof model !== "string" || model.trim().length === 0) {
|
|
201
|
+
throw new ProviderBatchError("google batch requests require a non-blank request.model");
|
|
202
|
+
}
|
|
203
|
+
const job = await client.batches.create({
|
|
204
|
+
model,
|
|
205
|
+
src: { inlinedRequests: [inlineRequest] },
|
|
206
|
+
});
|
|
207
|
+
const handle = { providerBatchId: job.name };
|
|
208
|
+
return handle;
|
|
209
|
+
},
|
|
210
|
+
async poll(handle) {
|
|
211
|
+
const job = await client.batches.get({ name: handle.providerBatchId });
|
|
212
|
+
const state = job.state ?? job.metadata?.state ?? "";
|
|
213
|
+
return { status: GOOGLE_TERMINAL_STATUS[state] ?? "pending" };
|
|
214
|
+
},
|
|
215
|
+
async readResult(handle) {
|
|
216
|
+
const job = await client.batches.get({ name: handle.providerBatchId });
|
|
217
|
+
const entries = job.dest?.inlinedResponses;
|
|
218
|
+
// A single-item batch is unambiguous by construction: index 0 is
|
|
219
|
+
// "our" item, the same way a custom_id would be for the other
|
|
220
|
+
// providers — there is no cross-item confusion possible here.
|
|
221
|
+
const entry = entries?.[0];
|
|
222
|
+
if (!entry) {
|
|
223
|
+
throw new ProviderBatchError("google batch produced no inline response");
|
|
224
|
+
}
|
|
225
|
+
if (entry.error != null) {
|
|
226
|
+
// Never surface the provider's own error text — only that this
|
|
227
|
+
// one item failed.
|
|
228
|
+
throw new ProviderBatchError("google batch item returned an error response");
|
|
229
|
+
}
|
|
230
|
+
if (!entry.response) {
|
|
231
|
+
throw new ProviderBatchError("google batch item had no response body");
|
|
232
|
+
}
|
|
233
|
+
return { result: entry.response, containedToolCallPlan: hasFunctionCallPart(entry.response) };
|
|
234
|
+
},
|
|
235
|
+
async direct(request) {
|
|
236
|
+
const response = await client.models.generateContent(request);
|
|
237
|
+
return { result: response, containedToolCallPlan: hasFunctionCallPart(response) };
|
|
238
|
+
},
|
|
239
|
+
};
|
|
240
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
export declare const CONFIG_DIRNAME = ".metergraph";
|
|
2
|
+
export declare const CONFIG_FILENAME = "config.json";
|
|
3
|
+
export declare const SUPPORTED_CONFIG_VERSION = 2;
|
|
4
|
+
export interface RepoConfig {
|
|
5
|
+
repository: string;
|
|
6
|
+
repoRoot: string;
|
|
7
|
+
}
|
|
8
|
+
/** Return 'owner/repo' from a GitHub SSH or HTTPS remote URL, or undefined
|
|
9
|
+
* if the URL isn't a recognized GitHub origin. */
|
|
10
|
+
export declare function normalizeGithubRemote(url: string): string | undefined;
|
|
11
|
+
/** Walk upward from appRoot looking for .metergraph/config.json. Returns
|
|
12
|
+
* undefined -- silently, the normal v1 state -- when nothing is found. */
|
|
13
|
+
export declare function discoverRepoConfig(appRoot: string): RepoConfig | undefined;
|
|
14
|
+
/** Create .metergraph/config.json if -- and only if -- it doesn't already
|
|
15
|
+
* exist. Uses O_CREAT|O_EXCL ("wx") for an atomic create-only-if-absent; a
|
|
16
|
+
* concurrent writer (or a file that appeared between discovery and this
|
|
17
|
+
* call) always wins over us, and we simply read back whatever is there. */
|
|
18
|
+
export declare function writeConfigAtomically(repoRoot: string, repository: string): RepoConfig | undefined;
|
|
19
|
+
/** Discover an existing repo config, or detect+write one once at the git top
|
|
20
|
+
* level. Fail-open: any detection or write failure returns undefined
|
|
21
|
+
* (legacy protocol v1), never throws. */
|
|
22
|
+
export declare function ensureRepoConfig(appRoot: string): RepoConfig | undefined;
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Repository-aware ingest protocol v2: discover, detect, and write
|
|
3
|
+
* .metergraph/config.json.
|
|
4
|
+
*
|
|
5
|
+
* Discovery is purely file-based (never shells out to git), so a committed
|
|
6
|
+
* config is honored in production without needing a .git directory at all.
|
|
7
|
+
* Detection + write only ever runs when discovery finds nothing: it shells
|
|
8
|
+
* out to git to find the repo's top level and GitHub origin, then writes the
|
|
9
|
+
* config there exactly once. An existing file is always authoritative and is
|
|
10
|
+
* never overwritten. Every failure mode here is fail-open -- callers get
|
|
11
|
+
* undefined and fall back to legacy protocol v1, never a thrown error.
|
|
12
|
+
*/
|
|
13
|
+
import { closeSync, mkdirSync, openSync, readFileSync, realpathSync, statSync, writeSync } from "node:fs";
|
|
14
|
+
import { dirname, isAbsolute, join, resolve } from "node:path";
|
|
15
|
+
export const CONFIG_DIRNAME = ".metergraph";
|
|
16
|
+
export const CONFIG_FILENAME = "config.json";
|
|
17
|
+
export const SUPPORTED_CONFIG_VERSION = 2;
|
|
18
|
+
const MAX_WALK_UP = 64;
|
|
19
|
+
const REMOTE_PATTERNS = [
|
|
20
|
+
/^git@github\.com:([^/]+\/[^/]+?)(\.git)?\/?$/,
|
|
21
|
+
/^https:\/\/github\.com\/([^/]+\/[^/]+?)(\.git)?\/?$/,
|
|
22
|
+
/^ssh:\/\/git@github\.com\/([^/]+\/[^/]+?)(\.git)?\/?$/,
|
|
23
|
+
];
|
|
24
|
+
/** Return 'owner/repo' from a GitHub SSH or HTTPS remote URL, or undefined
|
|
25
|
+
* if the URL isn't a recognized GitHub origin. */
|
|
26
|
+
export function normalizeGithubRemote(url) {
|
|
27
|
+
const trimmed = url.trim();
|
|
28
|
+
for (const pattern of REMOTE_PATTERNS) {
|
|
29
|
+
const match = pattern.exec(trimmed);
|
|
30
|
+
if (match)
|
|
31
|
+
return match[1];
|
|
32
|
+
}
|
|
33
|
+
return undefined;
|
|
34
|
+
}
|
|
35
|
+
function load(path, repoRoot) {
|
|
36
|
+
let doc;
|
|
37
|
+
try {
|
|
38
|
+
doc = JSON.parse(readFileSync(path, "utf8"));
|
|
39
|
+
}
|
|
40
|
+
catch (error) {
|
|
41
|
+
console.warn(`metergraph: found ${path} but could not read it: ${error instanceof Error ? error.message : String(error)}`);
|
|
42
|
+
return undefined;
|
|
43
|
+
}
|
|
44
|
+
if (typeof doc !== "object" || doc === null || doc.version !== SUPPORTED_CONFIG_VERSION) {
|
|
45
|
+
console.warn(`metergraph: ${path} has an unsupported schema version; ignoring (expected version ${SUPPORTED_CONFIG_VERSION})`);
|
|
46
|
+
return undefined;
|
|
47
|
+
}
|
|
48
|
+
const repository = doc.repository;
|
|
49
|
+
if (typeof repository !== "string" || !repository.includes("/")) {
|
|
50
|
+
console.warn(`metergraph: ${path} is missing a valid 'repository' field; ignoring`);
|
|
51
|
+
return undefined;
|
|
52
|
+
}
|
|
53
|
+
return { repository, repoRoot };
|
|
54
|
+
}
|
|
55
|
+
/** Walk upward from appRoot looking for .metergraph/config.json. Returns
|
|
56
|
+
* undefined -- silently, the normal v1 state -- when nothing is found. */
|
|
57
|
+
export function discoverRepoConfig(appRoot) {
|
|
58
|
+
let current;
|
|
59
|
+
try {
|
|
60
|
+
current = realpathSync(appRoot);
|
|
61
|
+
}
|
|
62
|
+
catch {
|
|
63
|
+
return undefined;
|
|
64
|
+
}
|
|
65
|
+
for (let i = 0; i < MAX_WALK_UP; i += 1) {
|
|
66
|
+
const candidate = join(current, CONFIG_DIRNAME, CONFIG_FILENAME);
|
|
67
|
+
try {
|
|
68
|
+
readFileSync(candidate);
|
|
69
|
+
return load(candidate, current);
|
|
70
|
+
}
|
|
71
|
+
catch {
|
|
72
|
+
// no config at this level; keep walking up
|
|
73
|
+
}
|
|
74
|
+
const parent = dirname(current);
|
|
75
|
+
if (parent === current)
|
|
76
|
+
break;
|
|
77
|
+
current = parent;
|
|
78
|
+
}
|
|
79
|
+
return undefined;
|
|
80
|
+
}
|
|
81
|
+
function gitDirectory(repoRoot) {
|
|
82
|
+
const marker = join(repoRoot, ".git");
|
|
83
|
+
try {
|
|
84
|
+
if (statSync(marker).isDirectory())
|
|
85
|
+
return marker;
|
|
86
|
+
const match = /^gitdir:\s*(.+)$/m.exec(readFileSync(marker, "utf8"));
|
|
87
|
+
const path = match?.[1];
|
|
88
|
+
if (!path)
|
|
89
|
+
return undefined;
|
|
90
|
+
return isAbsolute(path) ? path : resolve(repoRoot, path);
|
|
91
|
+
}
|
|
92
|
+
catch {
|
|
93
|
+
return undefined;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
function ownedByCurrentUser(path) {
|
|
97
|
+
if (typeof process.getuid !== "function")
|
|
98
|
+
return true;
|
|
99
|
+
try {
|
|
100
|
+
return statSync(path).uid === process.getuid();
|
|
101
|
+
}
|
|
102
|
+
catch {
|
|
103
|
+
return false;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
function gitTopLevel(appRoot) {
|
|
107
|
+
try {
|
|
108
|
+
let current = realpathSync(appRoot);
|
|
109
|
+
for (let i = 0; i < MAX_WALK_UP; i += 1) {
|
|
110
|
+
const gitDir = gitDirectory(current);
|
|
111
|
+
if (gitDir) {
|
|
112
|
+
// Match Git's safe-directory default: never trust repository metadata
|
|
113
|
+
// owned by another Unix user. Unsupported platforms retain v1's
|
|
114
|
+
// existing fail-open behavior.
|
|
115
|
+
return ownedByCurrentUser(current) && ownedByCurrentUser(gitDir)
|
|
116
|
+
? current
|
|
117
|
+
: undefined;
|
|
118
|
+
}
|
|
119
|
+
const parent = dirname(current);
|
|
120
|
+
if (parent === current)
|
|
121
|
+
break;
|
|
122
|
+
current = parent;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
// Fall through to the normal v1 path.
|
|
127
|
+
}
|
|
128
|
+
return undefined;
|
|
129
|
+
}
|
|
130
|
+
function gitOriginUrl(repoRoot) {
|
|
131
|
+
try {
|
|
132
|
+
const gitDir = gitDirectory(repoRoot);
|
|
133
|
+
if (!gitDir)
|
|
134
|
+
return undefined;
|
|
135
|
+
let commonDir = gitDir;
|
|
136
|
+
try {
|
|
137
|
+
const relative = readFileSync(join(gitDir, "commondir"), "utf8").trim();
|
|
138
|
+
if (relative)
|
|
139
|
+
commonDir = resolve(gitDir, relative);
|
|
140
|
+
}
|
|
141
|
+
catch {
|
|
142
|
+
// Normal repositories keep config directly in .git.
|
|
143
|
+
}
|
|
144
|
+
const config = readFileSync(join(commonDir, "config"), "utf8");
|
|
145
|
+
let inOrigin = false;
|
|
146
|
+
for (const line of config.split(/\r?\n/)) {
|
|
147
|
+
const section = /^\s*\[remote\s+"([^"]+)"\]\s*$/.exec(line);
|
|
148
|
+
if (section) {
|
|
149
|
+
inOrigin = section[1] === "origin";
|
|
150
|
+
continue;
|
|
151
|
+
}
|
|
152
|
+
if (/^\s*\[/.test(line))
|
|
153
|
+
inOrigin = false;
|
|
154
|
+
if (inOrigin) {
|
|
155
|
+
const url = /^\s*url\s*=\s*(.+?)\s*$/.exec(line);
|
|
156
|
+
if (url)
|
|
157
|
+
return url[1];
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
catch {
|
|
162
|
+
// Missing or unreadable Git metadata is the normal production fallback.
|
|
163
|
+
}
|
|
164
|
+
return undefined;
|
|
165
|
+
}
|
|
166
|
+
/** Create .metergraph/config.json if -- and only if -- it doesn't already
|
|
167
|
+
* exist. Uses O_CREAT|O_EXCL ("wx") for an atomic create-only-if-absent; a
|
|
168
|
+
* concurrent writer (or a file that appeared between discovery and this
|
|
169
|
+
* call) always wins over us, and we simply read back whatever is there. */
|
|
170
|
+
export function writeConfigAtomically(repoRoot, repository) {
|
|
171
|
+
const configDir = join(repoRoot, CONFIG_DIRNAME);
|
|
172
|
+
const configPath = join(configDir, CONFIG_FILENAME);
|
|
173
|
+
const payload = `${JSON.stringify({ version: SUPPORTED_CONFIG_VERSION, repository })}\n`;
|
|
174
|
+
try {
|
|
175
|
+
mkdirSync(configDir, { recursive: true });
|
|
176
|
+
const fd = openSync(configPath, "wx", 0o644);
|
|
177
|
+
try {
|
|
178
|
+
writeSync(fd, payload);
|
|
179
|
+
}
|
|
180
|
+
finally {
|
|
181
|
+
closeSync(fd);
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
catch (error) {
|
|
185
|
+
if (error.code !== "EEXIST") {
|
|
186
|
+
console.warn(`metergraph: could not write ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
|
|
187
|
+
return undefined;
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
return load(configPath, repoRoot);
|
|
191
|
+
}
|
|
192
|
+
/** Discover an existing repo config, or detect+write one once at the git top
|
|
193
|
+
* level. Fail-open: any detection or write failure returns undefined
|
|
194
|
+
* (legacy protocol v1), never throws. */
|
|
195
|
+
export function ensureRepoConfig(appRoot) {
|
|
196
|
+
const existing = discoverRepoConfig(appRoot);
|
|
197
|
+
if (existing)
|
|
198
|
+
return existing;
|
|
199
|
+
try {
|
|
200
|
+
const repoRoot = gitTopLevel(appRoot);
|
|
201
|
+
if (!repoRoot)
|
|
202
|
+
return undefined;
|
|
203
|
+
const origin = gitOriginUrl(repoRoot);
|
|
204
|
+
if (!origin)
|
|
205
|
+
return undefined;
|
|
206
|
+
const repository = normalizeGithubRemote(origin);
|
|
207
|
+
if (!repository)
|
|
208
|
+
return undefined;
|
|
209
|
+
return writeConfigAtomically(repoRoot, repository);
|
|
210
|
+
}
|
|
211
|
+
catch {
|
|
212
|
+
return undefined;
|
|
213
|
+
}
|
|
214
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export declare const DEFAULT_TIMEOUT_MS = 3000;
|
|
2
|
+
export declare const DEFAULT_TTL_MS = 300000;
|
|
3
|
+
export declare const REFRESH_MARGIN_MS = 30000;
|
|
4
|
+
export declare const MAX_BACKOFF_MS = 60000;
|
|
5
|
+
export declare class SessionManager {
|
|
6
|
+
private readonly appToken;
|
|
7
|
+
private readonly repository;
|
|
8
|
+
private readonly sdkVersion;
|
|
9
|
+
private readonly timeoutMs;
|
|
10
|
+
private readonly url;
|
|
11
|
+
private readonly failureLog;
|
|
12
|
+
private token;
|
|
13
|
+
private expiresAt;
|
|
14
|
+
private stopped;
|
|
15
|
+
private retryAt;
|
|
16
|
+
private backoffMs;
|
|
17
|
+
constructor(appToken: string, baseUrl: string, repository: string, sdkVersion: string, timeoutMs?: number);
|
|
18
|
+
getToken(): Promise<string | undefined>;
|
|
19
|
+
invalidate(): void;
|
|
20
|
+
stop(): void;
|
|
21
|
+
private exchange;
|
|
22
|
+
private markFailed;
|
|
23
|
+
}
|