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

main
ts 478 lines 16.2 KB
Raw
1 import * as apihub from "@distilled.cloud/gcp/apihub_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 {
9 alchemyLabelKeys,
10 createInternalLabels,
11 hasAlchemyLabels,
12 stripInternalLabels,
13 } from "../Labels.ts";
14 import { waitForOperation as waitForLongRunning, type LongRunningOperation } from "../Operation.ts";
15
16 export type AttributeValues = apihub.GoogleCloudApihubV1AttributeValues;
17 export type AttributeValuesMap = apihub.GoogleCloudApihubV1AttributeValuesMap;
18 export type Documentation = apihub.GoogleCloudApihubV1Documentation;
19
20 export const MAX_ID_LENGTH = 63;
21 export const MAX_INSTANCE_ID_LENGTH = 40;
22 export const MAX_DISPLAY_NAME_LENGTH = 64;
23
24 export class ApihubNotResolved extends Data.TaggedError("GCP.ApiHub.ResourceNotResolved")<{
25 resourceName: string;
26 }> {}
27
28 export class ApihubStillExists extends Data.TaggedError("GCP.ApiHub.StillExists")<{
29 resourceName: string;
30 }> {}
31
32 export const lastSegment = (value: string) => {
33 const trimmed = value.replace(/\/+$/, "");
34 const parts = trimmed.split("/");
35 return parts[parts.length - 1] || trimmed;
36 };
37
38 export const locationOf = (name: string, fallback: string) => {
39 const parts = name.split("/");
40 const index = parts.indexOf("locations");
41 return index >= 0 ? (parts[index + 1] ?? fallback) : fallback;
42 };
43
44 export const parentOf = (name: string) => {
45 const parts = name.split("/").filter((part) => part.length > 0);
46 return parts.slice(0, -2).join("/");
47 };
48
49 export const locationParent = (project: string, location: string) =>
50 `projects/${project}/locations/${location}`;
51
52 export const normalizeLocation = (location: string | undefined, defaultLocation: string) =>
53 lastSegment(location ?? defaultLocation).toLowerCase();
54
55 export const parseResourceName = (name: string, collection: string, defaultLocation: string) => {
56 const parts = name.split("/").filter((part) => part.length > 0);
57 const collectionAt = parts.lastIndexOf(collection);
58 const locationsAt = parts.lastIndexOf("locations");
59 const projectsAt = parts.lastIndexOf("projects");
60 const pluginsAt = parts.lastIndexOf("plugins");
61 return {
62 project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
63 location:
64 locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : defaultLocation,
65 id: collectionAt >= 0 && parts[collectionAt + 1] ? parts[collectionAt + 1]! : lastSegment(name),
66 pluginId: pluginsAt >= 0 && parts[pluginsAt + 1] ? parts[pluginsAt + 1]! : "",
67 plugin: pluginsAt >= 0 ? parts.slice(0, pluginsAt + 2).join("/") : undefined,
68 parent:
69 collectionAt > 0
70 ? parts.slice(0, collectionAt).join("/")
71 : parts.slice(0, Math.max(0, parts.length - 1)).join("/"),
72 };
73 };
74
75 export const expandParent = (
76 value: string,
77 project: string,
78 location: string,
79 collection: string,
80 ) => {
81 if (value.includes("/")) return value.replace(/\/+$/, "");
82 return `projects/${project}/locations/${location}/${collection}/${value}`;
83 };
84
85 export const rfc1035 = (name: string, maxLength = MAX_ID_LENGTH): string => {
86 let next = name
87 .toLowerCase()
88 .replace(/[^a-z0-9-]/g, "-")
89 .replace(/-+/g, "-")
90 .replace(/^-+|-+$/g, "");
91 if (!/^[a-z]/.test(next)) next = `a${next}`;
92 next = next.slice(0, maxLength).replace(/-+$/g, "");
93 if (next.length === 0) return "apihub";
94 if (next.length < 4) next = `${next}xxxx`.slice(0, maxLength);
95 if (!/[a-z0-9]$/.test(next)) next = `${next.slice(0, maxLength - 1)}0`;
96 return next.slice(0, maxLength);
97 };
98
99 export const toPhysicalId = (
100 id: string,
101 explicit: string | undefined,
102 existing: string | undefined,
103 maxLength = MAX_ID_LENGTH,
104 ) =>
105 Effect.gen(function* () {
106 if (explicit !== undefined) return explicit;
107 if (existing !== undefined) return existing;
108 return rfc1035(yield* createPhysicalName({ id, maxLength, lowercase: true }), maxLength);
109 });
110
111 export const userLabels = (
112 labels: Record<string, string | undefined> | null | undefined,
113 ): Record<string, string> => stripInternalLabels(tagRecord(labels));
114
115 export const hasAlchemyLabelMap = (labels: Record<string, string | undefined> | null | undefined) =>
116 Object.keys(labels ?? {}).some((key) => key.startsWith("alchemy-"));
117
118 const markerOf = (labels: Record<string, string>) =>
119 `[alchemy ${alchemyLabelKeys.stack}=${labels[alchemyLabelKeys.stack]} ${alchemyLabelKeys.stage}=${labels[alchemyLabelKeys.stage]} ${alchemyLabelKeys.id}=${labels[alchemyLabelKeys.id]}]`;
120
121 const fitMarker = (labels: Record<string, string>, maxLength: number) => {
122 let stack = labels[alchemyLabelKeys.stack] ?? "x";
123 let stage = labels[alchemyLabelKeys.stage] ?? "x";
124 let id = labels[alchemyLabelKeys.id] ?? "x";
125 let marker = markerOf({
126 [alchemyLabelKeys.stack]: stack,
127 [alchemyLabelKeys.stage]: stage,
128 [alchemyLabelKeys.id]: id,
129 });
130 while (marker.length > maxLength && (stack.length > 1 || stage.length > 1 || id.length > 1)) {
131 if (stack.length >= stage.length && stack.length >= id.length) {
132 stack = stack.slice(0, -1);
133 } else if (stage.length >= id.length) {
134 stage = stage.slice(0, -1);
135 } else {
136 id = id.slice(0, -1);
137 }
138 marker = markerOf({
139 [alchemyLabelKeys.stack]: stack,
140 [alchemyLabelKeys.stage]: stage,
141 [alchemyLabelKeys.id]: id,
142 });
143 }
144 return marker.slice(0, maxLength);
145 };
146
147 export const encodeOwnership = (
148 labels: Record<string, string>,
149 text: string | undefined,
150 ): string => {
151 const marker = fitMarker(labels, 8000);
152 const trimmed = text?.trim();
153 return trimmed && trimmed.length > 0 ? `${marker}\n${trimmed}` : marker;
154 };
155
156 export const encodeOwnershipLine = (
157 labels: Record<string, string>,
158 text: string | undefined,
159 maxLength = MAX_DISPLAY_NAME_LENGTH,
160 ): string => {
161 const trimmed = text?.replace(/[\r\n]+/g, " ").trim();
162 if (!trimmed) return fitMarker(labels, maxLength);
163 const minMarker = 24;
164 const reserved = Math.min(trimmed.length + 1, Math.max(0, maxLength - minMarker));
165 const marker = fitMarker(labels, maxLength - reserved);
166 return `${marker} ${trimmed}`.slice(0, maxLength);
167 };
168
169 export const parseOwnership = (
170 text: string | undefined,
171 ): {
172 labels: Record<string, string>;
173 text: string | undefined;
174 } => {
175 if (!text?.includes("[alchemy ")) {
176 return { labels: {}, text };
177 }
178 const start = text.indexOf("[alchemy ");
179 const end = text.indexOf("]", start);
180 if (end < 0) return { labels: {}, text };
181 const labels: Record<string, string> = {};
182 for (const part of text.slice(start + "[alchemy ".length, end).split(/\s+/)) {
183 const eq = part.indexOf("=");
184 if (eq > 0) {
185 labels[part.slice(0, eq)] = part.slice(eq + 1);
186 }
187 }
188 const before = text.slice(0, start).trim();
189 const after = text.slice(end + 1).replace(/^[\s\n]+/, "");
190 const rest = [before, after].filter((part) => part.length > 0).join("\n");
191 return { labels, text: rest.length > 0 ? rest : undefined };
192 };
193
194 export const hasOwnershipMarker = (text: string | undefined) =>
195 Object.keys(parseOwnership(text).labels).some((key) => key.startsWith("alchemy-"));
196
197 const prefixMatch = (expected: string, observed: string) =>
198 expected === observed || expected.startsWith(observed) || observed.startsWith(expected);
199
200 export const ownedByAlchemy = (id: string, text: string | undefined) =>
201 Effect.gen(function* () {
202 const expected = yield* createInternalLabels(id);
203 const { labels } = parseOwnership(text);
204 if (!hasOwnershipMarker(text)) return false;
205 const exact = yield* hasAlchemyLabels(id, labels);
206 if (exact) return true;
207 return (
208 prefixMatch(expected[alchemyLabelKeys.stack] ?? "", labels[alchemyLabelKeys.stack] ?? "") &&
209 prefixMatch(expected[alchemyLabelKeys.stage] ?? "", labels[alchemyLabelKeys.stage] ?? "") &&
210 prefixMatch(expected[alchemyLabelKeys.id] ?? "", labels[alchemyLabelKeys.id] ?? "")
211 );
212 });
213
214 export const createOwnership = (id: string) => createInternalLabels(id);
215
216 export const canonical = (value: unknown): unknown => {
217 if (value === undefined || value === null) return undefined;
218 if (typeof value === "boolean" || typeof value === "number") return value;
219 if (typeof value === "string") {
220 return value.length === 0 ? undefined : value;
221 }
222 if (Array.isArray(value)) {
223 const items = value.map(canonical).filter((item) => item !== undefined);
224 return items.length === 0 ? undefined : items;
225 }
226 if (typeof value === "object") {
227 const entries = Object.entries(value as Record<string, unknown>)
228 .map(([key, item]) => [key, canonical(item)] as const)
229 .filter(([, item]) => item !== undefined)
230 .sort(([left], [right]) => left.localeCompare(right));
231 if (entries.length === 0) return undefined;
232 return Object.fromEntries(entries);
233 }
234 return undefined;
235 };
236
237 export const fingerprint = (value: unknown): string => JSON.stringify(canonical(value) ?? null);
238
239 export const sameJson = (left: unknown, right: unknown) => fingerprint(left) === fingerprint(right);
240
241 export const sameText = (left: string | undefined, right: string | undefined) =>
242 (left ?? "") === (right ?? "");
243
244 export const sameStringList = (
245 left: readonly string[] | undefined,
246 right: readonly string[] | undefined,
247 ) => JSON.stringify([...(left ?? [])].sort()) === JSON.stringify([...(right ?? [])].sort());
248
249 export const updateMaskOf = (...fields: Array<string | undefined>) =>
250 fields.filter((field): field is string => field !== undefined).join(",");
251
252 export const replaceOnIdentity = (input: {
253 previousId: string | undefined;
254 nextId: string | undefined;
255 previousLocation: string;
256 nextLocation: string;
257 extra?: boolean;
258 previousParent?: string;
259 nextParent?: string;
260 }) => {
261 const parentChanged =
262 (input.previousParent ?? "") !== "" &&
263 (input.nextParent ?? "") !== "" &&
264 (input.previousParent ?? "") !== (input.nextParent ?? "");
265 const replace =
266 (input.extra ?? false) ||
267 parentChanged ||
268 (input.previousId !== undefined &&
269 input.nextId !== undefined &&
270 input.nextId !== input.previousId) ||
271 input.previousLocation !== input.nextLocation;
272 if (!replace) return undefined;
273 const samePhysical =
274 input.previousLocation === input.nextLocation &&
275 !parentChanged &&
276 input.previousId !== undefined &&
277 input.nextId === input.previousId;
278 return {
279 action: "replace" as const,
280 deleteFirst: samePhysical,
281 };
282 };
283
284 export const waitUntilExists = <A, E extends { readonly _tag: string }, R>(
285 get: Effect.Effect<A, E, R>,
286 name: string,
287 ) =>
288 get.pipe(
289 Effect.filterOrFail(
290 (value): value is Exclude<A, undefined> => value !== undefined,
291 () => new ApihubNotResolved({ resourceName: name }),
292 ),
293 Effect.retry({
294 while: (error) => error._tag === "GCP.ApiHub.ResourceNotResolved",
295 times: 8,
296 schedule: Schedule.spaced("1 second"),
297 }),
298 );
299
300 export const waitUntilGone = <A, E extends { readonly _tag: string }, R>(
301 get: Effect.Effect<A, E, R>,
302 name: string,
303 ) =>
304 get.pipe(
305 Effect.filterOrFail(
306 (value) => value === undefined,
307 () => new ApihubStillExists({ resourceName: name }),
308 ),
309 Effect.retry({
310 while: (error) => error._tag === "GCP.ApiHub.StillExists",
311 times: 10,
312 schedule: Schedule.spaced("1 second"),
313 }),
314 Effect.asVoid,
315 );
316
317 export const collectPages = <Page, Item, E, R>(
318 stream: Stream.Stream<Page, E, R>,
319 pick: (page: Page) => readonly Item[] | undefined,
320 ) =>
321 stream.pipe(
322 Stream.flatMap((page) => Stream.fromIterable(pick(page) ?? [])),
323 Stream.runCollect,
324 Effect.map((chunk) => Array.from(chunk)),
325 );
326
327 export const emptyOnMissing = <A, E extends { readonly _tag: string }, R>(
328 effect: Effect.Effect<A, E, R>,
329 fallback: A,
330 ) =>
331 effect.pipe(
332 Effect.catchIf(
333 (error) => error._tag === "NotFound",
334 () => Effect.succeed(fallback),
335 ),
336 );
337
338 export const listItems = <Page, Item, E extends { readonly _tag: string }, R>(
339 pages: Stream.Stream<Page, E, R>,
340 pick: (page: Page) => readonly Item[] | undefined,
341 ) => emptyOnMissing(collectPages(pages, pick), [] as Item[]);
342
343 export const listApis = (parent: string) =>
344 listItems(
345 apihub.listProjectsLocationsApis.pages({ parent, pageSize: 1000 }),
346 (page) => page.apis,
347 );
348
349 export const listVersions = (api: string) =>
350 listItems(
351 apihub.listProjectsLocationsApisVersions.pages({
352 parent: api,
353 pageSize: 1000,
354 }),
355 (page) => page.versions,
356 );
357
358 export const listOperations = (version: string) =>
359 listItems(
360 apihub.listProjectsLocationsApisVersionsOperations.pages({
361 parent: version,
362 pageSize: 1000,
363 }),
364 (page) => page.apiOperations,
365 );
366
367 export const listSpecs = (version: string) =>
368 listItems(
369 apihub.listProjectsLocationsApisVersionsSpecs.pages({
370 parent: version,
371 pageSize: 1000,
372 }),
373 (page) => page.specs,
374 );
375
376 export const listAttributes = (parent: string) =>
377 listItems(
378 apihub.listProjectsLocationsAttributes.pages({ parent, pageSize: 1000 }),
379 (page) => page.attributes,
380 );
381
382 export const listCurations = (parent: string) =>
383 listItems(
384 apihub.listProjectsLocationsCurations.pages({ parent, pageSize: 1000 }),
385 (page) => page.curations,
386 );
387
388 export const listDependencies = (parent: string) =>
389 listItems(
390 apihub.listProjectsLocationsDependencies.pages({ parent, pageSize: 1000 }),
391 (page) => page.dependencies,
392 );
393
394 export const listChildResources = <A, E, R>(
395 parents: readonly { name?: string }[],
396 list: (name: string) => Effect.Effect<A[], E, R>,
397 ) =>
398 Effect.forEach(
399 parents.filter((parent) => (parent.name ?? "").length > 0),
400 (parent) => list(parent.name!),
401 { concurrency: 4 },
402 ).pipe(Effect.map((groups) => groups.flat()));
403
404 export const encodeContents = (contents: string) =>
405 Effect.sync(() => Buffer.from(contents, "utf8").toString("base64"));
406
407 export const openApiSpecType = (
408 project: string,
409 location: string,
410 ): apihub.GoogleCloudApihubV1AttributeValues => ({
411 attribute: `projects/${project}/locations/${location}/attributes/system-spec-type`,
412 enumValues: {
413 values: [{ id: "openapi", displayName: "OpenAPI Spec" }],
414 },
415 });
416
417 export const ownershipLabels = createInternalLabels;
418 export const parseName = parseResourceName;
419 export const MAX_LONG_ID_LENGTH = 128;
420 export const MAX_PLUGIN_DISPLAY_NAME_LENGTH = 50;
421 export const MAX_PLUGIN_INSTANCE_DISPLAY_NAME_LENGTH = 255;
422
423 export const DEFAULT_PLUGIN_ACTIONS: apihub.GoogleCloudApihubV1PluginActionConfigList = [
424 {
425 id: "sync-metadata",
426 displayName: "Sync metadata",
427 description: "Sync API metadata into API hub",
428 triggerMode: "API_HUB_ON_DEMAND_TRIGGER",
429 },
430 ];
431
432 export const DEFAULT_DEPLOYMENT_TYPE: apihub.GoogleCloudApihubV1AttributeValues = {
433 enumValues: { values: [{ id: "apigee" }] },
434 };
435
436 export const projectIdOf = (value: string | undefined, fallback = "") =>
437 lastSegment(value && value.length > 0 ? value : fallback);
438
439 export const projectNameOf = (value: string | undefined, fallback = "") => {
440 const raw = value && value.length > 0 ? value : fallback;
441 return raw.startsWith("projects/") ? raw : `projects/${lastSegment(raw)}`;
442 };
443
444 export class ApihubInstanceFailed extends Data.TaggedError("GCP.ApiHub.InstanceFailed")<{
445 resourceName: string;
446 state?: string;
447 message?: string;
448 }> {}
449
450 /** API hub instance provisioning takes up to ~15 minutes. */
451 const OPERATION_BUDGET = "20 minutes";
452
453 /**
454 * Wait for a long-running operation. ALREADY_EXISTS (code 6) means a
455 * concurrent create won the race; reconcile observes the resource next.
456 */
457 export const waitForOperation = (operation: LongRunningOperation) =>
458 waitForLongRunning(operation, (name) => apihub.getProjectsLocationsOperations({ name }), {
459 budget: OPERATION_BUDGET,
460 }).pipe(
461 Effect.catchIf(
462 (error) => error._tag === "GCP.OperationFailed" && error.code === 6,
463 () => Effect.succeed(operation),
464 ),
465 );
466
467 /**
468 * Wait for a delete operation. A vanished operation or NOT_FOUND (code 5)
469 * means the resource is already gone.
470 */
471 export const waitForDeleteOperation = (operation: LongRunningOperation) =>
472 waitForOperation(operation).pipe(
473 Effect.catchIf(
474 (error) =>
475 error._tag === "NotFound" || (error._tag === "GCP.OperationFailed" && error.code === 5),
476 () => Effect.succeed(operation),
477 ),
478 );