@microagi/alchemy-gcp 0.1.2

package/lib/ServiceNetworking/PsaConnection.js

@@ -0,0 +1,130 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as sn from "@distilled.cloud/gcp/servicenetworking-v1";
+import { Resource } from "alchemy";
+import { deepEqual, isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+export const PsaConnection = Resource("GCP.PsaConnection");
+const DEFAULT_SERVICE = "servicenetworking.googleapis.com";
+const serviceParent = (service) => service.startsWith("services/") ? service : `services/${service}`;
+export const PsaConnectionProvider = () => Provider.effect(PsaConnection, Effect.gen(function* () {
+    const listConnections = yield* sn.listServicesConnections;
+    const createConnection = yield* sn.createServicesConnections;
+    const patchConnection = yield* sn.patchServicesConnections;
+    const deleteConnection = yield* sn.deleteConnectionServicesConnections;
+    const getOperations = yield* sn.getOperations;
+    const awaitOperation = Effect.fn(function* (operationName, session) {
+        const op = yield* getOperations({ name: operationName }).pipe(Effect.flatMap((current) => current.done === true
+            ? Effect.succeed(current)
+            : Effect.fail({ _tag: "OperationPending" })), Effect.retry({
+            while: (e) => e?._tag === "OperationPending",
+            schedule: Schedule.exponential(Duration.seconds(2), 1.5).pipe(Schedule.either(Schedule.spaced(Duration.seconds(15))), 
+            // PSA peering creates can take 5–10 min while the
+            // service producer provisions its side. 80 × 15s ≈ 20 min.
+            Schedule.both(Schedule.recurs(80)), Schedule.tapOutput(() => session.note(`Waiting for ServiceNetworking operation ${operationName}…`))),
+        }));
+        if (op.error) {
+            return yield* new ConfigError({
+                message: `ServiceNetworking operation ${operationName} failed: ${op.error.message ?? JSON.stringify(op.error)}`,
+            });
+        }
+        return op;
+    });
+    // List connections in the consumer VPC and return the matching
+    // one (there can be at most one connection per `(network, service)`
+    // pair). 404/403 collapse to "not present".
+    const observe = (parent, network) => listConnections({ parent, network }).pipe(Effect.map((res) => (res.connections ?? []).find((c) => c.network === network)), Effect.catchTag("NotFound", () => Effect.succeed(undefined)), Effect.catchTag("Forbidden", () => Effect.succeed(undefined)));
+    return {
+        stables: ["network", "serviceName", "peering"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+            if (!isResolved(news))
+                return undefined;
+            const oldsService = olds.service ?? DEFAULT_SERVICE;
+            const newsService = news.service ?? DEFAULT_SERVICE;
+            if ((olds.network !== undefined && olds.network !== news.network) ||
+                (olds.service !== undefined && oldsService !== newsService)) {
+                return { action: "replace" };
+            }
+            return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+            const service = news.service ?? DEFAULT_SERVICE;
+            const parent = serviceParent(service);
+            const desired = [...news.reservedPeeringRanges].sort();
+            let observed = yield* observe(parent, news.network);
+            if (!observed) {
+                const op = yield* createConnection({
+                    parent,
+                    body: {
+                        network: news.network,
+                        reservedPeeringRanges: desired,
+                    },
+                }).pipe(Effect.catchTag("Conflict", () => Effect.succeed(undefined)));
+                if (op?.name)
+                    yield* awaitOperation(op.name, session);
+                observed = yield* observe(parent, news.network);
+            }
+            if (!observed) {
+                return yield* new ConfigError({
+                    message: `PSA connection on ${news.network} did not appear after create.`,
+                });
+            }
+            // Sync reserved ranges. `force=true` is required when removing
+            // a previously-assigned range; we pass it unconditionally to
+            // keep the patch idempotent regardless of which direction the
+            // diff went.
+            const observedRanges = [...(observed.reservedPeeringRanges ?? [])].sort();
+            if (!deepEqual(observedRanges, desired) && observed.peering) {
+                const op = yield* patchConnection({
+                    name: `${parent}/connections/${observed.peering}`,
+                    force: true,
+                    updateMask: "reservedPeeringRanges",
+                    body: {
+                        network: news.network,
+                        reservedPeeringRanges: desired,
+                    },
+                });
+                if (op.name)
+                    yield* awaitOperation(op.name, session);
+                observed = yield* observe(parent, news.network);
+            }
+            return {
+                network: news.network,
+                serviceName: parent,
+                peering: observed?.peering ?? "",
+                reservedPeeringRanges: observed?.reservedPeeringRanges ?? desired,
+            };
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+            if (!output.peering)
+                return; // Never fully created.
+            yield* deleteConnection({
+                name: `${output.serviceName}/connections/${output.peering}`,
+                body: { consumerNetwork: output.network },
+            }).pipe(Effect.flatMap((op) => op.name ? awaitOperation(op.name, session) : Effect.succeed(op)), Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        read: Effect.fn(function* ({ output, olds }) {
+            const network = output?.network ?? olds?.network;
+            const service = olds?.service ?? DEFAULT_SERVICE;
+            const parent = output?.serviceName ?? serviceParent(service);
+            if (!network)
+                return undefined;
+            const observed = yield* observe(parent, network);
+            if (!observed)
+                return undefined;
+            // No ownership concept: PSA connections are unique per
+            // `(network, service)`, and the operation can only be
+            // performed by the consumer-VPC project owner. Adoption is
+            // permissive — same stance as `ApiEnable`.
+            return {
+                network,
+                serviceName: parent,
+                peering: observed.peering ?? "",
+                reservedPeeringRanges: observed.reservedPeeringRanges ?? [],
+            };
+        }),
+    };
+}));
+//# sourceMappingURL=PsaConnection.js.map

package/lib/ServiceNetworking/PsaConnection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PsaConnection.js","sourceRoot":"","sources":["../../src/ServiceNetworking/PsaConnection.ts"],"names":[],"mappings":"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"}

package/lib/ServiceNetworking/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./PsaConnection.ts";
+//# sourceMappingURL=index.d.ts.map

package/lib/ServiceNetworking/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ServiceNetworking/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/lib/ServiceNetworking/index.js

@@ -0,0 +1,2 @@
+export * from "./PsaConnection.js";
+//# sourceMappingURL=index.js.map

package/lib/ServiceNetworking/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ServiceNetworking/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/lib/ServiceUsage/ApiEnable.d.ts

@@ -0,0 +1,78 @@
+import { Resource } from "alchemy";
+import * as Provider from "alchemy/Provider";
+import type * as GCP from "../Providers.ts";
+/**
+ * Enable a Google Cloud API on a project (`serviceusage.googleapis.com`
+ * `services.enable`). Required before any operation against the
+ * underlying API will succeed — e.g. a fresh `GCP.Project` cannot host
+ * a `GCP.Cluster` until `container.googleapis.com` is enabled.
+ *
+ * The resource is keyed by `(project, service)`; both are immutable —
+ * changing either replaces.
+ *
+ * `delete` calls `services.disable`, which GCP rejects with HTTP 400
+ * (`FAILED_PRECONDITION`) if the service is already disabled or has
+ * dependent services in use. We treat "already disabled" as success
+ * (idempotent teardown). Other 400s propagate so the user sees the
+ * real reason (typically: another service depends on this one).
+ */
+export type ApiEnableProps = {
+    /** GCP project ID hosting the API enablement. Immutable — replace. */
+    project: string;
+    /**
+     * Fully-qualified service name, e.g. `container.googleapis.com`,
+     * `compute.googleapis.com`, `iam.googleapis.com`. Immutable — replace.
+     */
+    service: string;
+};
+export type ApiEnableAttributes = {
+    /** GCP project ID, threaded through from props. */
+    project: string;
+    /** Service name, threaded through from props. */
+    service: string;
+    /** Resource name in the form `projects/{project}/services/{service}`. */
+    name: string;
+    /** Lifecycle state — `"ENABLED"` once the LRO completes. */
+    state: string;
+};
+/**
+ * @section Enabling APIs
+ *
+ * **Dependency edges are explicit.** Alchemy sequences resources by the
+ * Output references they consume. To make a downstream resource (e.g.
+ * `GCP.Cluster`) wait for the API enable, route its `project` prop
+ * through `apiEnable.project` rather than `project.projectId`:
+ *
+ * @example Container API for GKE
+ * ```typescript
+ * const project = yield* GCP.Project("Research", { ... });
+ * const containerApi = yield* GCP.ApiEnable("ContainerApi", {
+ *   project: project.projectId,
+ *   service: "container.googleapis.com",
+ * });
+ * const cluster = yield* GCP.Cluster("Main", {
+ *   project: containerApi.project, // ← edge through ApiEnable, not Project
+ *   location: "us-central1-a",
+ *   // ...
+ * });
+ * ```
+ *
+ * If the cluster instead read `project.projectId`, alchemy would
+ * schedule the cluster create in parallel with the API enable and the
+ * GKE call would fail with `Forbidden: <X> API has not been used in
+ * project ... before or it is disabled.`
+ *
+ * @example Multiple APIs on a project
+ * ```typescript
+ * const containerApi = yield* GCP.ApiEnable("ContainerApi",
+ *   { project: project.projectId, service: "container.googleapis.com" });
+ * const computeApi = yield* GCP.ApiEnable("ComputeApi",
+ *   { project: project.projectId, service: "compute.googleapis.com" });
+ * // Then route downstream resources through the API enables that gate them:
+ * const cluster = yield* GCP.Cluster("Main", { project: containerApi.project, ... });
+ * ```
+ */
+export type ApiEnable = Resource<"GCP.ApiEnable", ApiEnableProps, ApiEnableAttributes, never, GCP.Providers>;
+export declare const ApiEnable: import("alchemy").ResourceClass<ApiEnable>;
+export declare const ApiEnableProvider: () => import("effect/Layer").Layer<Provider.Provider<ApiEnable>, never, import("effect/unstable/http/HttpClient").HttpClient | import("@distilled.cloud/gcp").Credentials>;
+//# sourceMappingURL=ApiEnable.d.ts.map

package/lib/ServiceUsage/ApiEnable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiEnable.d.ts","sourceRoot":"","sources":["../../src/ServiceUsage/ApiEnable.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAI7C,OAAO,KAAK,KAAK,GAAG,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAC9B,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,KAAK,EACL,GAAG,CAAC,SAAS,CACd,CAAC;AAEF,eAAO,MAAM,SAAS,4CAAuC,CAAC;AAK9D,eAAO,MAAM,iBAAiB,4KAyK3B,CAAC"}

package/lib/ServiceUsage/ApiEnable.js

@@ -0,0 +1,132 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as su from "@distilled.cloud/gcp/serviceusage-v1";
+import { Resource } from "alchemy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+export const ApiEnable = Resource("GCP.ApiEnable");
+const fqServiceName = (project, service) => `projects/${project}/services/${service}`;
+export const ApiEnableProvider = () => Provider.effect(ApiEnable, Effect.gen(function* () {
+    const getServices = yield* su.getServices;
+    const enableServices = yield* su.enableServices;
+    const disableServices = yield* su.disableServices;
+    const getOperations = yield* su.getOperations;
+    // Service Usage `Operation` carries `.done: boolean` (matching CRM,
+    // NOT Container's `.status: "DONE"`), so we can't reuse the
+    // Container `makeAwaitOperation`. Mirror Project.ts's polling
+    // schedule (cheap polls for fast LROs; service enable usually
+    // resolves in <30s).
+    const awaitOperation = Effect.fn(function* (operationName, session) {
+        const op = yield* getOperations({ name: operationName }).pipe(Effect.flatMap((current) => current.done === true
+            ? Effect.succeed(current)
+            : Effect.fail({ _tag: "OperationPending" })), Effect.retry({
+            while: (e) => e?._tag === "OperationPending",
+            schedule: Schedule.exponential(Duration.seconds(1), 1.5).pipe(Schedule.either(Schedule.spaced(Duration.seconds(15))), Schedule.both(Schedule.recurs(60)), Schedule.tapOutput(() => session.note(`Waiting for ServiceUsage operation ${operationName}…`))),
+        }));
+        if (op.error) {
+            return yield* new ConfigError({
+                message: `ServiceUsage operation ${operationName} failed: ${op.error.message ?? JSON.stringify(op.error)}`,
+            });
+        }
+        return op;
+    });
+    return {
+        // No physical-name generation: identity is `(project, service)`.
+        // Both are static strings on `news`/`olds`/`output`.
+        stables: ["project", "service", "name"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+            if (!isResolved(news))
+                return undefined;
+            if ((olds.project !== undefined && olds.project !== news.project) ||
+                (olds.service !== undefined && olds.service !== news.service)) {
+                return { action: "replace" };
+            }
+            return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+            const name = fqServiceName(news.project, news.service);
+            // `getServices` returns the service entity even when disabled
+            // (state="DISABLED"), so 404 here means an invalid service
+            // name, not "not enabled". Treat NotFound and Forbidden as
+            // "needs enable attempt" — the enable call will surface the
+            // real error.
+            let observed = yield* getServices({ name }).pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)), Effect.catchTag("Forbidden", () => Effect.succeed(undefined)));
+            if (!observed || observed.state !== "ENABLED") {
+                // `Conflict` here covers concurrent enable / state-persistence
+                // race; fall through and re-observe.
+                const op = yield* enableServices({ name, body: {} }).pipe(Effect.catchTag("Conflict", () => Effect.succeed(undefined)));
+                if (op?.name)
+                    yield* awaitOperation(op.name, session);
+                observed = yield* getServices({ name });
+            }
+            return {
+                project: news.project,
+                service: news.service,
+                name: observed.name ?? name,
+                state: observed.state ?? "ENABLED",
+            };
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+            const name = fqServiceName(output.project, output.service);
+            yield* disableServices({
+                name,
+                body: { disableDependentServices: false },
+            }).pipe(Effect.flatMap((op) => op.name ? awaitOperation(op.name, session) : Effect.succeed(op)), Effect.catchTag("NotFound", () => Effect.void), 
+            // GCP returns HTTP 400 in two important cases on disable
+            // that we treat as idempotent success:
+            //
+            // 1. Service already disabled. The resource is gone from
+            //    the user's perspective; alchemy is removing it from
+            //    state.
+            //
+            // 2. "Resources are found when disabling service(s) X.
+            //    Before you can disable, please delete the following
+            //    resources first: …" — this is GCP's eventual-
+            //    consistency lag: a sibling resource (cluster, node
+            //    pool) was deleted via its own API but ServiceUsage's
+            //    "what's still using this service" view hasn't
+            //    propagated yet. The cluster is gone; alchemy state is
+            //    being torn down; if the project itself is also being
+            //    destroyed (the typical case in `stack.destroy`), all
+            //    API state goes with it. Failing here would leave a
+            //    half-torn-down stack the user has to clean up by
+            //    hand.
+            //
+            // Other 400s (e.g. dependent *services* still enabled, or
+            // a true API-level rejection) propagate so the user sees
+            // the real failure.
+            Effect.catchTag("BadRequest", (e) => /already.*disabled|not.*currently enabled|FAILED_PRECONDITION|Resources are found/i.test(e.message ?? "")
+                ? Effect.void
+                : Effect.fail(e)));
+        }),
+        read: Effect.fn(function* ({ output, olds }) {
+            const project = output?.project ?? olds?.project;
+            const service = output?.service ?? olds?.service;
+            if (!project || !service)
+                return undefined;
+            const name = fqServiceName(project, service);
+            const observed = yield* getServices({ name }).pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)), Effect.catchTag("Forbidden", () => Effect.succeed(undefined)));
+            if (!observed)
+                return undefined;
+            // A DISABLED service is functionally absent from this
+            // resource's perspective — the engine treats `undefined` as
+            // "needs reconcile" and the next plan will re-enable.
+            if (observed.state !== "ENABLED")
+                return undefined;
+            // No `alchemy_*` ownership labels available on services
+            // (no labels field), so we can't gate via `Unowned`.
+            // API enablement is project-scoped state, not a labeled
+            // resource — adoption is fine: any project we can read from
+            // has the API enabled regardless of who turned it on.
+            return {
+                project,
+                service,
+                name: observed.name ?? name,
+                state: observed.state,
+            };
+        }),
+    };
+}));
+//# sourceMappingURL=ApiEnable.js.map

package/lib/ServiceUsage/ApiEnable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiEnable.js","sourceRoot":"","sources":["../../src/ServiceUsage/ApiEnable.ts"],"names":[],"mappings":"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"}

package/lib/ServiceUsage/index.d.ts

@@ -0,0 +1,3 @@
+export { ApiEnable, ApiEnableProvider } from "./ApiEnable.ts";
+export type { ApiEnableAttributes, ApiEnableProps } from "./ApiEnable.ts";
+//# sourceMappingURL=index.d.ts.map

package/lib/ServiceUsage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ServiceUsage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/lib/ServiceUsage/index.js

@@ -0,0 +1,2 @@
+export { ApiEnable, ApiEnableProvider } from "./ApiEnable.js";
+//# sourceMappingURL=index.js.map

package/lib/ServiceUsage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ServiceUsage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/lib/Tags.d.ts

@@ -0,0 +1,57 @@
+import * as Effect from "effect/Effect";
+import { Stack } from "alchemy/Stack";
+import { Stage } from "alchemy/Stage";
+/**
+ * GCP labels are stricter than AWS tags:
+ *
+ * - **Keys** must match `[a-z][a-z0-9_-]{0,62}`. Alchemy's default
+ *   `createInternalTags` returns keys like `alchemy::stack` — `:` is
+ *   illegal in a GCP label key, so we use `_` separators here.
+ * - **Values** must match `[a-z0-9_-]{0,63}`. We lowercase and replace
+ *   any out-of-range character with `-`.
+ *
+ * The label values together with the keys are what `read` uses to
+ * decide whether a project is owned by this stack/stage/id (returning
+ * plain attrs) or foreign (returning `Unowned(attrs)`).
+ *
+ * @see {@link https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements}
+ */
+declare const LABEL_KEY_APP = "alchemy_app";
+declare const LABEL_KEY_STAGE = "alchemy_stage";
+declare const LABEL_KEY_ID = "alchemy_id";
+/**
+ * Compute the alchemy-internal label set for a Resource. Merge the
+ * result with user-provided labels (user wins on key collision is
+ * deliberately disallowed — alchemy keys are reserved).
+ */
+export declare const gcpInternalLabels: (id: string) => Effect.Effect<{
+    alchemy_app: string;
+    alchemy_stage: string;
+    alchemy_id: string;
+}, never, Stage | Stack>;
+/**
+ * True when `labels` contains all three alchemy-internal keys with
+ * values matching this stack/stage/id. Used in `read` to decide
+ * adoption ownership.
+ */
+export declare const hasAlchemyLabels: (id: string, labels: Record<string, string> | undefined) => Effect.Effect<boolean, never, Stage | Stack>;
+export { LABEL_KEY_APP as ALCHEMY_LABEL_APP, LABEL_KEY_STAGE as ALCHEMY_LABEL_STAGE, LABEL_KEY_ID as ALCHEMY_LABEL_ID, };
+/**
+ * Compose `[alchemy:...] <userDescription?>`. Pass through to the
+ * resource's `description` body field at create time.
+ */
+export declare const gcpAlchemyDescription: (id: string, userDescription?: string | undefined) => Effect.Effect<string, never, Stage | Stack>;
+/**
+ * True when `description` begins with an alchemy marker matching this
+ * stack/stage/id. Used in `read` for resources that lack a labels
+ * field.
+ */
+export declare const descriptionHasAlchemyMarker: (id: string, description: string | undefined) => Effect.Effect<boolean, never, Stage | Stack>;
+/**
+ * Strip the leading alchemy marker (if any) and return what remains —
+ * used when surfacing the user-visible description back through
+ * Attributes. Matches whether the marker was generated by us or not;
+ * if there's no marker, returns the description unchanged.
+ */
+export declare const stripAlchemyMarker: (description: string | undefined) => string | undefined;
+//# sourceMappingURL=Tags.d.ts.map

package/lib/Tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tags.d.ts","sourceRoot":"","sources":["../src/Tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AAEH,QAAA,MAAM,aAAa,gBAAgB,CAAC;AACpC,QAAA,MAAM,eAAe,kBAAkB,CAAC;AACxC,QAAA,MAAM,YAAY,eAAe,CAAC;AAQlC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;wBAQ5B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,0GAW3B,CAAC;AAEH,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,eAAe,IAAI,mBAAmB,EACtC,YAAY,IAAI,gBAAgB,GACjC,CAAC;AAsBF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,mGAQhC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,+FAStC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,aAAa,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAI7E,CAAC"}

package/lib/Tags.js

@@ -0,0 +1,106 @@
+import * as Effect from "effect/Effect";
+import { Stack } from "alchemy/Stack";
+import { Stage } from "alchemy/Stage";
+/**
+ * GCP labels are stricter than AWS tags:
+ *
+ * - **Keys** must match `[a-z][a-z0-9_-]{0,62}`. Alchemy's default
+ *   `createInternalTags` returns keys like `alchemy::stack` — `:` is
+ *   illegal in a GCP label key, so we use `_` separators here.
+ * - **Values** must match `[a-z0-9_-]{0,63}`. We lowercase and replace
+ *   any out-of-range character with `-`.
+ *
+ * The label values together with the keys are what `read` uses to
+ * decide whether a project is owned by this stack/stage/id (returning
+ * plain attrs) or foreign (returning `Unowned(attrs)`).
+ *
+ * @see {@link https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements}
+ */
+const LABEL_KEY_APP = "alchemy_app";
+const LABEL_KEY_STAGE = "alchemy_stage";
+const LABEL_KEY_ID = "alchemy_id";
+const sanitizeLabelValue = (raw) => {
+    const lowered = raw.toLowerCase();
+    const replaced = lowered.replace(/[^a-z0-9_-]/g, "-");
+    return replaced.slice(0, 63);
+};
+/**
+ * Compute the alchemy-internal label set for a Resource. Merge the
+ * result with user-provided labels (user wins on key collision is
+ * deliberately disallowed — alchemy keys are reserved).
+ */
+export const gcpInternalLabels = Effect.fnUntraced(function* (id) {
+    const stack = yield* Stack;
+    const stage = yield* Stage;
+    return {
+        [LABEL_KEY_APP]: sanitizeLabelValue(stack.name),
+        [LABEL_KEY_STAGE]: sanitizeLabelValue(stage),
+        [LABEL_KEY_ID]: sanitizeLabelValue(id),
+    };
+});
+/**
+ * True when `labels` contains all three alchemy-internal keys with
+ * values matching this stack/stage/id. Used in `read` to decide
+ * adoption ownership.
+ */
+export const hasAlchemyLabels = Effect.fnUntraced(function* (id, labels) {
+    if (!labels)
+        return false;
+    const expected = yield* gcpInternalLabels(id);
+    return (labels[LABEL_KEY_APP] === expected[LABEL_KEY_APP] &&
+        labels[LABEL_KEY_STAGE] === expected[LABEL_KEY_STAGE] &&
+        labels[LABEL_KEY_ID] === expected[LABEL_KEY_ID]);
+});
+export { LABEL_KEY_APP as ALCHEMY_LABEL_APP, LABEL_KEY_STAGE as ALCHEMY_LABEL_STAGE, LABEL_KEY_ID as ALCHEMY_LABEL_ID, };
+/**
+ * Some GCP resources (compute Networks, Subnetworks) carry no labels
+ * field, so the label-based adoption gate cannot apply. For these we
+ * encode the same `(app, stage, id)` triple as a sentinel inside the
+ * resource's `description` field — created on insert and read back on
+ * adoption.
+ *
+ * Format: `[alchemy:app=<app>,stage=<stage>,id=<id>] <user description>`.
+ * The leading bracketed segment is what `descriptionHasAlchemyMarker`
+ * matches; everything after the closing `]` is the user-supplied
+ * description and is preserved as-is. We never *update* this marker
+ * because both Network and Subnetwork treat `description` as immutable
+ * after create — the marker is only ever written on insert.
+ */
+const sanitizeMarkerValue = (raw) => raw.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 63);
+const buildMarkerPrefix = (app, stage, id) => `[alchemy:app=${sanitizeMarkerValue(app)},stage=${sanitizeMarkerValue(stage)},id=${sanitizeMarkerValue(id)}]`;
+/**
+ * Compose `[alchemy:...] <userDescription?>`. Pass through to the
+ * resource's `description` body field at create time.
+ */
+export const gcpAlchemyDescription = Effect.fnUntraced(function* (id, userDescription) {
+    const stack = yield* Stack;
+    const stage = yield* Stage;
+    const prefix = buildMarkerPrefix(stack.name, stage, id);
+    return userDescription ? `${prefix} ${userDescription}` : prefix;
+});
+/**
+ * True when `description` begins with an alchemy marker matching this
+ * stack/stage/id. Used in `read` for resources that lack a labels
+ * field.
+ */
+export const descriptionHasAlchemyMarker = Effect.fnUntraced(function* (id, description) {
+    if (!description)
+        return false;
+    const stack = yield* Stack;
+    const stage = yield* Stage;
+    const expected = buildMarkerPrefix(stack.name, stage, id);
+    return description.startsWith(expected);
+});
+/**
+ * Strip the leading alchemy marker (if any) and return what remains —
+ * used when surfacing the user-visible description back through
+ * Attributes. Matches whether the marker was generated by us or not;
+ * if there's no marker, returns the description unchanged.
+ */
+export const stripAlchemyMarker = (description) => {
+    if (!description)
+        return description;
+    const m = description.match(/^\[alchemy:[^\]]+\]\s?/);
+    return m ? description.slice(m[0].length) || undefined : description;
+};
+//# sourceMappingURL=Tags.js.map

package/lib/Tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tags.js","sourceRoot":"","sources":["../src/Tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AAEH,MAAM,aAAa,GAAG,aAAa,CAAC;AACpC,MAAM,eAAe,GAAG,eAAe,CAAC;AACxC,MAAM,YAAY,GAAG,YAAY,CAAC;AAElC,MAAM,kBAAkB,GAAG,CAAC,GAAW,EAAU,EAAE;IACjD,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/B,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,EAAU;IACtE,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC;IAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC;IAC3B,OAAO;QACL,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC;QAC/C,CAAC,eAAe,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC;QAC5C,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC,EAAE,CAAC;KACN,CAAC;AACrC,CAAC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EACzD,EAAU,EACV,MAA0C;IAE1C,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAC9C,OAAO,CACL,MAAM,CAAC,aAAa,CAAC,KAAK,QAAQ,CAAC,aAAa,CAAC;QACjD,MAAM,CAAC,eAAe,CAAC,KAAK,QAAQ,CAAC,eAAe,CAAC;QACrD,MAAM,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,YAAY,CAAC,CAChD,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,eAAe,IAAI,mBAAmB,EACtC,YAAY,IAAI,gBAAgB,GACjC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,mBAAmB,GAAG,CAAC,GAAW,EAAU,EAAE,CAClD,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAE9D,MAAM,iBAAiB,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,EAAU,EAAU,EAAE,CAC3E,gBAAgB,mBAAmB,CAAC,GAAG,CAAC,UAAU,mBAAmB,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,EAAE,CAAC,GAAG,CAAC;AAEhH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAC9D,EAAU,EACV,eAAwB;IAExB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC;IAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC;IAC3B,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO,eAAe,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AACnE,CAAC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EACpE,EAAU,EACV,WAA+B;IAE/B,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC;IAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC;IAC3B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1D,OAAO,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC1C,CAAC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,WAA+B,EAAsB,EAAE;IACxF,IAAI,CAAC,WAAW;QAAE,OAAO,WAAW,CAAC;IACrC,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACtD,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;AACvE,CAAC,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+export { Credentials, fromADC, fromAuthProvider } from "./Auth/Credentials.ts";
+export { GCP_AUTH_PROVIDER_NAME, GCPAuth, } from "./Auth/AuthProvider.ts";
+export type { GCPAuthConfig, GCPResolvedCredentials, } from "./Auth/AuthProvider.ts";
+export * from "./CloudResourceManager/index.ts";
+export * from "./Compute/index.ts";
+export * from "./Container/index.ts";
+export * from "./Parallelstore/index.ts";
+export * from "./ServiceNetworking/index.ts";
+export * from "./ServiceUsage/index.ts";
+export * from "./Providers.ts";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,aAAa,EACb,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC"}

package/lib/index.js

@@ -0,0 +1,10 @@
+export { Credentials, fromADC, fromAuthProvider } from "./Auth/Credentials.js";
+export { GCP_AUTH_PROVIDER_NAME, GCPAuth, } from "./Auth/AuthProvider.js";
+export * from "./CloudResourceManager/index.js";
+export * from "./Compute/index.js";
+export * from "./Container/index.js";
+export * from "./Parallelstore/index.js";
+export * from "./ServiceNetworking/index.js";
+export * from "./ServiceUsage/index.js";
+export * from "./Providers.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAKhC,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC"}