The best way to control Claude Code, Codex and more from any computer or phone

main
ts 402 lines 13.5 KB
Raw
1 import * as documentai from "@distilled.cloud/gcp/documentai_v1";
2 import { createPhysicalName } from "alchemy/PhysicalName";
3 import { tagRecord } from "alchemy/Tags";
4 import * as Data from "effect/Data";
5 import * as Effect from "effect/Effect";
6 import * as Schedule from "effect/Schedule";
7 import * as Stream from "effect/Stream";
8 import { isTransientGcpError } from "../Errors.ts";
9 import {
10 alchemyLabelKeys,
11 createInternalLabels,
12 hasAlchemyLabels,
13 stripInternalLabels,
14 } from "../Labels.ts";
15
16 // Document AI is only served from the `us` / `eu` multi-region deployments, so the
17 // default stays `us` rather than following `GCP.Region`.
18 export const DEFAULT_LOCATION = "us";
19 /**
20 * The distilled Document AI client talks to `documentai.googleapis.com`
21 * (the US deployment). Listing processors/schemas in `eu` or regional
22 * locations against that host returns HTTP 400 INVALID_ARGUMENT
23 * (`Invalid location: '…' must match the server deployment 'us'`).
24 */
25 export const LIST_LOCATIONS = ["us"] as const;
26 export const MAX_PROCESSOR_DISPLAY_NAME_LENGTH = 64;
27 export const MAX_DISPLAY_NAME_LENGTH = 128;
28 export const DEFAULT_PROCESSOR_TYPE = "OCR_PROCESSOR";
29
30 export class ResourceNotResolved extends Data.TaggedError("GCP.DocumentAI.ResourceNotResolved")<{
31 resourceName: string;
32 }> {}
33
34 export class ResourceStillExists extends Data.TaggedError("GCP.DocumentAI.ResourceStillExists")<{
35 resourceName: string;
36 }> {}
37
38 export class ProcessorPending extends Data.TaggedError("GCP.DocumentAI.ProcessorPending")<{
39 resourceName: string;
40 state: string;
41 }> {}
42
43 export class ProcessorFailed extends Data.TaggedError("GCP.DocumentAI.ProcessorFailed")<{
44 resourceName: string;
45 state: string;
46 }> {}
47
48 export const lastSegment = (value: string) => {
49 const trimmed = value.replace(/\/+$/, "");
50 const parts = trimmed.split("/");
51 return parts[parts.length - 1] || trimmed;
52 };
53
54 export const locationParent = (project: string, location: string) =>
55 `projects/${project}/locations/${location}`;
56
57 export const normalizeLocation = (location: string | undefined) =>
58 lastSegment(location ?? DEFAULT_LOCATION).toLowerCase();
59
60 export const parseResourceName = (name: string, collection: string) => {
61 const parts = name.split("/").filter((part) => part.length > 0);
62 const collectionAt = parts.lastIndexOf(collection);
63 const locationsAt = parts.lastIndexOf("locations");
64 const projectsAt = parts.lastIndexOf("projects");
65 return {
66 project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
67 location:
68 locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : DEFAULT_LOCATION,
69 id: collectionAt >= 0 && parts[collectionAt + 1] ? parts[collectionAt + 1]! : lastSegment(name),
70 parent:
71 collectionAt > 0
72 ? parts.slice(0, collectionAt).join("/")
73 : parts.slice(0, Math.max(0, parts.length - 1)).join("/"),
74 };
75 };
76
77 export const expandParent = (
78 value: string,
79 project: string,
80 location: string,
81 collection: string,
82 ) => {
83 if (value.includes("/")) return value.replace(/\/+$/, "");
84 return `${locationParent(project, location)}/${collection}/${value}`;
85 };
86
87 export const sameText = (left: string | undefined, right: string | undefined) =>
88 (left ?? "") === (right ?? "");
89
90 export const canonical = (value: unknown): unknown => {
91 if (value === undefined || value === null) return undefined;
92 if (typeof value === "boolean" || typeof value === "number") return value;
93 if (typeof value === "string") {
94 return value.length === 0 ? undefined : value;
95 }
96 if (Array.isArray(value)) {
97 const items = value.map(canonical).filter((item) => item !== undefined);
98 return items.length === 0 ? undefined : items;
99 }
100 if (typeof value === "object") {
101 const entries = Object.entries(value as Record<string, unknown>)
102 .map(([key, item]) => [key, canonical(item)] as const)
103 .filter(([, item]) => item !== undefined)
104 .sort(([left], [right]) => left.localeCompare(right));
105 if (entries.length === 0) return undefined;
106 return Object.fromEntries(entries);
107 }
108 return undefined;
109 };
110
111 export const fingerprint = (value: unknown): string => JSON.stringify(canonical(value) ?? null);
112
113 export const sameJson = (left: unknown, right: unknown) => fingerprint(left) === fingerprint(right);
114
115 export const updateMaskOf = (...fields: Array<string | undefined>) =>
116 fields.filter((field): field is string => field !== undefined).join(",");
117
118 export const userLabels = (
119 labels: Record<string, string | undefined> | null | undefined,
120 ): Record<string, string> => stripInternalLabels(tagRecord(labels));
121
122 export const hasAlchemyLabelMap = (labels: Record<string, string | undefined> | null | undefined) =>
123 Object.keys(labels ?? {}).some((key) => key.startsWith("alchemy-"));
124
125 const compactMarkerOf = (stack: string, stage: string, id: string) =>
126 `[alc ${stack} ${stage} ${id}]`;
127
128 const shrinkMarker = (
129 labels: Record<string, string>,
130 maxLength: number,
131 build: (stack: string, stage: string, id: string) => string,
132 ) => {
133 let stack = labels[alchemyLabelKeys.stack] ?? "x";
134 let stage = labels[alchemyLabelKeys.stage] ?? "x";
135 let id = labels[alchemyLabelKeys.id] ?? "x";
136 let marker = build(stack, stage, id);
137 while (marker.length > maxLength && (stack.length > 1 || stage.length > 1 || id.length > 1)) {
138 if (stack.length >= stage.length && stack.length >= id.length) {
139 stack = stack.slice(0, -1);
140 } else if (stage.length >= id.length) {
141 stage = stage.slice(0, -1);
142 } else {
143 id = id.slice(0, -1);
144 }
145 marker = build(stack, stage, id);
146 }
147 return marker.slice(0, maxLength);
148 };
149
150 export const encodeOwnershipLine = (
151 labels: Record<string, string>,
152 text: string | undefined,
153 maxLength = MAX_DISPLAY_NAME_LENGTH,
154 ): string => {
155 const trimmed = text?.replace(/[\r\n]+/g, " ").trim();
156 const suffix = trimmed && trimmed.length > 0 ? ` ${trimmed}` : "";
157 const markerMax = Math.min(maxLength, Math.max(12, maxLength - suffix.length));
158 const marker = shrinkMarker(labels, markerMax, compactMarkerOf);
159 return `${marker}${suffix}`.slice(0, maxLength);
160 };
161
162 export const parseOwnership = (
163 text: string | undefined,
164 ): {
165 labels: Record<string, string>;
166 text: string | undefined;
167 } => {
168 if (text?.startsWith("[alc ")) {
169 const end = text.indexOf("]");
170 if (end < 0) return { labels: {}, text };
171 const parts = text.slice("[alc ".length, end).trim().split(/\s+/);
172 const labels: Record<string, string> = {};
173 if (parts[0]) labels[alchemyLabelKeys.stack] = parts[0]!;
174 if (parts[1]) labels[alchemyLabelKeys.stage] = parts[1]!;
175 if (parts[2]) labels[alchemyLabelKeys.id] = parts[2]!;
176 const rest = text.slice(end + 1).replace(/^[\s\n]+/, "");
177 return { labels, text: rest.length > 0 ? rest : undefined };
178 }
179 if (!text?.startsWith("[alchemy ")) {
180 return { labels: {}, text };
181 }
182 const end = text.indexOf("]");
183 if (end < 0) return { labels: {}, text };
184 const labels: Record<string, string> = {};
185 for (const part of text.slice("[alchemy ".length, end).split(/\s+/)) {
186 const eq = part.indexOf("=");
187 if (eq > 0) {
188 labels[part.slice(0, eq)] = part.slice(eq + 1);
189 }
190 }
191 const rest = text.slice(end + 1).replace(/^[\s\n]+/, "");
192 return { labels, text: rest.length > 0 ? rest : undefined };
193 };
194
195 export const hasOwnershipMarker = (text: string | undefined) =>
196 Object.keys(parseOwnership(text).labels).some((key) => key.startsWith("alchemy-"));
197
198 const prefixMatch = (expected: string, observed: string) =>
199 expected === observed || expected.startsWith(observed) || observed.startsWith(expected);
200
201 export const ownedByAlchemy = (id: string, text: string | undefined) =>
202 Effect.gen(function* () {
203 const expected = yield* createInternalLabels(id);
204 const { labels } = parseOwnership(text);
205 if (!hasOwnershipMarker(text)) return false;
206 const exact = yield* hasAlchemyLabels(id, labels);
207 if (exact) return true;
208 return (
209 prefixMatch(expected[alchemyLabelKeys.stack] ?? "", labels[alchemyLabelKeys.stack] ?? "") &&
210 prefixMatch(expected[alchemyLabelKeys.stage] ?? "", labels[alchemyLabelKeys.stage] ?? "") &&
211 prefixMatch(expected[alchemyLabelKeys.id] ?? "", labels[alchemyLabelKeys.id] ?? "")
212 );
213 });
214
215 export const toPhysicalId = (
216 id: string,
217 explicit: string | undefined,
218 existing: string | undefined,
219 maxLength = 32,
220 ) =>
221 Effect.gen(function* () {
222 if (explicit !== undefined) return explicit;
223 if (existing !== undefined) return existing;
224 return yield* createPhysicalName({
225 id,
226 maxLength,
227 lowercase: true,
228 });
229 });
230
231 export const replaceOnIdentity = (input: {
232 previousId?: string;
233 nextId?: string;
234 previousLocation?: string;
235 nextLocation?: string;
236 extra?: boolean;
237 }) => {
238 const previousLocation = normalizeLocation(input.previousLocation);
239 const nextLocation = normalizeLocation(input.nextLocation);
240 const replace =
241 (input.extra ?? false) ||
242 (input.previousId !== undefined &&
243 input.nextId !== undefined &&
244 input.nextId !== input.previousId) ||
245 (input.previousLocation !== undefined && previousLocation !== nextLocation);
246 if (!replace) return undefined;
247 const samePhysical =
248 previousLocation === nextLocation &&
249 input.previousId !== undefined &&
250 input.nextId === input.previousId;
251 return {
252 action: "replace" as const,
253 deleteFirst: samePhysical,
254 };
255 };
256
257 export const retryTransient = <A, E extends { readonly _tag: string }, R>(
258 effect: Effect.Effect<A, E, R>,
259 ) =>
260 effect.pipe(
261 Effect.retry({
262 while: isTransientGcpError,
263 times: 8,
264 schedule: Schedule.exponential("250 millis"),
265 }),
266 );
267
268 export const waitUntilGone = <A, E, R>(
269 get: Effect.Effect<A | undefined, E, R>,
270 name: string,
271 ): Effect.Effect<void, E | ResourceStillExists, R> =>
272 get.pipe(
273 Effect.filterOrFail(
274 (value) => value === undefined,
275 () => new ResourceStillExists({ resourceName: name }),
276 ),
277 Effect.retry({
278 while: (error) => error instanceof ResourceStillExists,
279 times: 10,
280 schedule: Schedule.spaced("2 seconds"),
281 }),
282 Effect.asVoid,
283 );
284
285 export const collectPages = <Page, Item, E, R>(
286 pages: Stream.Stream<Page, E, R>,
287 items: (page: Page) => readonly Item[] | null | undefined,
288 ) =>
289 pages.pipe(
290 Stream.flatMap((page) => Stream.fromIterable(items(page) ?? [])),
291 Stream.runCollect,
292 Effect.map((chunk) => Array.from(chunk) as Item[]),
293 );
294
295 const emptyList = <A>() => Effect.succeed<A[]>([]);
296
297 export const listLocationParents = (project: string) =>
298 Effect.succeed(LIST_LOCATIONS.map((location) => locationParent(project, location)));
299
300 export const listProcessorsAt = (parent: string) =>
301 parent.length === 0
302 ? emptyList<documentai.GoogleCloudDocumentaiV1Processor>()
303 : collectPages(
304 documentai.listProjectsLocationsProcessors.pages({
305 parent,
306 pageSize: 100,
307 }),
308 (page) => page.processors,
309 ).pipe(
310 Effect.catchTag("NotFound", () => emptyList<documentai.GoogleCloudDocumentaiV1Processor>()),
311 );
312
313 export const listSchemasAt = (parent: string) =>
314 parent.length === 0
315 ? emptyList<documentai.GoogleCloudDocumentaiV1NextSchema>()
316 : collectPages(
317 documentai.listProjectsLocationsSchemas.pages({
318 parent,
319 pageSize: 20,
320 }),
321 (page) => page.schemas,
322 ).pipe(
323 Effect.catchTag("NotFound", () =>
324 emptyList<documentai.GoogleCloudDocumentaiV1NextSchema>(),
325 ),
326 );
327
328 export const listSchemaVersionsAt = (parent: string) =>
329 parent.length === 0
330 ? emptyList<documentai.GoogleCloudDocumentaiV1SchemaVersion>()
331 : collectPages(
332 documentai.listProjectsLocationsSchemasSchemaVersions.pages({
333 parent,
334 pageSize: 20,
335 }),
336 (page) => page.schemaVersions,
337 ).pipe(
338 Effect.catchTag("NotFound", () =>
339 emptyList<documentai.GoogleCloudDocumentaiV1SchemaVersion>(),
340 ),
341 );
342
343 export const listProjectProcessors = (project: string) =>
344 Effect.gen(function* () {
345 const parents = yield* listLocationParents(project);
346 const groups = yield* Effect.forEach(parents, listProcessorsAt, {
347 concurrency: 2,
348 });
349 const seen = new Set<string>();
350 const processors: documentai.GoogleCloudDocumentaiV1Processor[] = [];
351 for (const processor of groups.flat()) {
352 const name = processor.name ?? "";
353 if (name.length === 0 || seen.has(name)) continue;
354 seen.add(name);
355 processors.push(processor);
356 }
357 return processors;
358 });
359
360 export const listProjectSchemas = (project: string) =>
361 Effect.gen(function* () {
362 const parents = yield* listLocationParents(project);
363 const groups = yield* Effect.forEach(parents, listSchemasAt, {
364 concurrency: 2,
365 });
366 const seen = new Set<string>();
367 const schemas: documentai.GoogleCloudDocumentaiV1NextSchema[] = [];
368 for (const schema of groups.flat()) {
369 const name = schema.name ?? "";
370 if (name.length === 0 || seen.has(name)) continue;
371 seen.add(name);
372 schemas.push(schema);
373 }
374 return schemas;
375 });
376
377 export const findOwnedByDisplayName = <T extends { name?: string; displayName?: string }>(
378 id: string,
379 items: readonly T[],
380 ) =>
381 Effect.gen(function* () {
382 for (const item of items) {
383 if (yield* ownedByAlchemy(id, item.displayName)) return item;
384 }
385 return undefined as T | undefined;
386 });
387
388 export const findOwnedByLabels = <
389 T extends {
390 name?: string;
391 labels?: Record<string, string | undefined> | null;
392 },
393 >(
394 id: string,
395 items: readonly T[],
396 ) =>
397 Effect.gen(function* () {
398 for (const item of items) {
399 if (yield* hasAlchemyLabels(id, tagRecord(item.labels))) return item;
400 }
401 return undefined as T | undefined;
402 });