@microagi/alchemy-gcp 0.2.1 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+All notable changes to `@microagi/alchemy-gcp`. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this package
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.5.0 — 2026-06-07
+
+Artifact Registry (artifactregistry v1) — Docker repositories, both
+standard (self-hosted builds) and remote (pull-through caches for
+Docker Hub and arbitrary upstreams like `nvcr.io`).
+
+### Added
+
+- **`GCP.ArtifactRegistryRepository`** — Artifact Registry repository
+  resource for `format: "DOCKER"`. Supports:
+  - `mode: "STANDARD_REPOSITORY"` — repository hosts images uploaded
+    by the project (CI builds, etc.).
+  - `mode: "REMOTE_REPOSITORY"` — pull-through cache. The upstream is
+    either a Google-known preset (`{ publicRepository: "DOCKER_HUB" }`)
+    or an arbitrary HTTPS Docker registry
+    (`{ customRepository: { uri: "https://nvcr.io" } }`). Optional
+    `upstreamCredentials` for authenticated upstreams (Secret
+    Manager-backed password).
+  - Mutable-via-patch fields: `description`, `labels`, `dockerConfig`
+    (`immutableTags`), `cleanupPolicies`, `cleanupPolicyDryRun` —
+    diff'd against observed cloud state and patched with a precise
+    `updateMask`.
+  - Replace triggers: `project`, `location`, `name`, `format`, `mode`,
+    `kmsKeyName`, and any change to `remoteRepositoryConfig` (GCP
+    refuses in-place updates here).
+  - Standard adoption gate via `alchemy_*` labels — pre-existing
+    repositories without our labels surface as `Unowned` and require
+    `--adopt` to take over.
+  - Same API-enable propagation retry (15s × 20 ≈ 5 min) as
+    `Cluster` / `Service` / `SqlInstance` for the race between
+    `ApiEnable` and the first create.
+- **Plan-time validation** — repo-name regex
+  (`/^[a-z0-9][a-z0-9-]{0,62}$/`), and the
+  `mode` ↔ `remoteRepositoryConfig` invariant (REMOTE requires a
+  docker upstream; STANDARD forbids a remote config). Fails fast with
+  typed `ConfigError` before any state mutation.
+- **Branded literal types** — `ArtifactRegistryFormat` (DOCKER,
+  MAVEN, …) and `ArtifactRegistryMode`
+  (STANDARD/REMOTE/VIRTUAL_REPOSITORY) with `(string & {})` tails for
+  forward-compat with new server-side values.
+
+### LRO
+
+- `ArtifactRegistry/Operations.ts` — Cloud Run-style poller. AR
+  operations use the standard `GoogleLongrunningOperation` shape
+  (`.done: boolean`), distinct from Sqladmin's tri-state `.status`.
+  Operation names are fully-qualified
+  (`projects/{p}/locations/{l}/operations/{id}`).
+
+## 0.4.0 — 2026-06-07
+
+Cloud SQL (sqladmin v1) — Postgres instance + database + user, with
+first-class IAM database authentication.
+
+### Added
+
+- **`GCP.SqlInstance`** — Cloud SQL for Postgres instance. Tier,
+  edition, disk auto-resize, IP configuration (public IPv4 + private
+  IP via PSA), backups + PITR, database flags, deletion protection,
+  zonal/regional HA. Optimistic concurrency via the live
+  `settings.settingsVersion` round-trip (Cloud SQL's `etag` field is
+  deprecated). API-enable-propagation 403 retry mirroring the
+  `Cluster` / `Service` providers.
+- **`GCP.SqlDatabase`** — logical Postgres database. Thin resource —
+  name, charset, collation. No labels on the GCP side so adoption is
+  best-effort (no `Unowned` wrapper).
+- **`GCP.SqlUser`** — Postgres role with three auth modes:
+  - `BUILT_IN` — username + `Redacted` password.
+  - `CLOUD_IAM_USER` — human IAM principal authenticated via the
+    Cloud SQL Auth Proxy / IAM token exchange.
+  - `CLOUD_IAM_SERVICE_ACCOUNT` — GCP service-account principal
+    (name = SA email minus the `.gserviceaccount.com` tail).
+  Plan-time validation rejects passwords on IAM users and missing
+  passwords on `BUILT_IN`. Forward-compat `(string & {})` tail keeps
+  newer IAM variants (`CLOUD_IAM_GROUP*`, `ENTRAID_USER`) reachable.
+- **Branded literal types** from `Sqladmin/Types.ts` —
+  `PostgresVersion` (15/16/17 only — narrower than distilled's
+  open-tailed enum so typos are caught at compile time), `SqlEdition`,
+  `SqlDataDiskType`, `SqlAvailabilityType`, `SqlActivationPolicy`,
+  `SqlUserType`.
+- **Plan-time validation** — instance name regex (1–98 chars,
+  RFC 1123 label subset), database name length, user password/type
+  consistency. Fails fast with a typed `ConfigError` before any state
+  mutation.
+- **`BadRequest` passthroughs** on `Instance`/`Database`/`User`
+  create/patch/delete — billing-not-enabled, missing PSA peering,
+  and invalid tier get remediation hints; anything else propagates
+  verbatim.
+
+### Notes
+
+- Sqladmin operations use `status: "DONE"` (distinct from the
+  `done: boolean` shape Cloud Resource Manager / Cloud Run / Lustre
+  use). `Sqladmin/Operations.ts` polls `getOperations({ project,
+  operation })` accordingly.
+- `SqlInstance` adoption is label-gated through
+  `settings.userLabels`. `SqlDatabase` and `SqlUser` cannot carry
+  labels, so they trust the logical id / parent address alone — be
+  cautious with `--adopt` on those.
+
+## 0.3.0 — 2026-05-11
+
+Cloud Run v2 — production polish on the Service + Job + IAM surface.
+
+### Added
+
+- **`GCP.Service`** — Cloud Run v2 HTTP service. Traffic routing,
+  ingress controls (`INGRESS_TRAFFIC_ALL` / `INTERNAL_ONLY` /
+  `INTERNAL_LOAD_BALANCER`), launch-stage gating, server-side
+  template diffing, label-gated adoption, and full LRO polling.
+- **`GCP.Job`** — Cloud Run v2 batch workload. Declarative
+  definition of the Job (template, parallelism, task count, retries,
+  GPU node selectors); execution is imperative via
+  `runProjectsLocationsJobs` (documented in the resource JSDoc).
+- **`GCP.serviceIamMember`** / **`GCP.jobIamMember`** — target-side
+  IAM binding helpers. Provider unions all bindings per target and
+  writes a single `setIamPolicy` per reconcile, preserving foreign
+  roles and members. Etag round-trip absorbs CI/human contention.
+- **Clean type re-exports** from the top level — `GCP.RevisionTemplate`,
+  `GCP.ExecutionTemplate`, `GCP.TaskTemplate`, `GCP.Container`,
+  `GCP.TrafficTarget`, `GCP.VpcAccess`, `GCP.NodeSelector`, etc. —
+  so consumers no longer need to import from `@distilled.cloud/gcp`
+  directly.
+- **Plan-time validation** for Cloud Run resources — name regex
+  (`<50 chars`, RFC 1123 label subset), reserved label/annotation
+  namespaces (`run.googleapis.com/`, `cloud.googleapis.com/`,
+  `serving.knative.dev/`, `autoscaling.knative.dev/`), and
+  template-must-have-containers. Fails fast with a typed
+  `ConfigError` before any state mutation.
+- **`BadRequest` passthroughs** on Cloud Run create + patch — wrap
+  the underlying GCP message with a remediation hint for billing
+  not enabled, image-not-in-approved-registry, and reserved-namespace
+  failures.
+
+### Changed
+
+- **Optimistic concurrency** on Cloud Run Service + Job — patch and
+  delete now pass the observed `etag` so concurrent edits (e.g. via
+  `gcloud run services update`) surface as `Conflict` instead of
+  silently overwriting.
+- README rewritten with categorised resource sections and Cloud Run
+  examples.
+
+### Notes
+
+`apps/cluster` and other downstream stacks bumping past `0.2.x` should
+swap `invokerIamDisabled: true` (sledgehammer) for the declarative
+`serviceIamMember(svc, "Public", { role: "roles/run.invoker", member: "allUsers" })`
+binding where possible — IAM history is auditable; the flag is not.
+
+## 0.2.x
+
+Pre-0.3 history is in `git log` — see commits up to and including
+`c6bcb9d Add Cloud Run v2 Service resource`. Highlights:
+
+- 0.2.0 — initial Cloud Run Service support (no IAM, no Job).
+- 0.1.x — Project, ApiEnable, Cluster, NodePool, Network, Subnetwork,
+  PsaConnection, GlobalAddress, SharedVpcHost, SharedVpcServiceProject,
+  ManagedLustreInstance.

package/README.md

@@ -79,27 +79,79 @@ bun alchemy destroy ./alchemy.run.ts
 
 `Alchemy.localState()` writes Alchemy's resource state to `.alchemy/` next to the stack file. `Alchemy.inMemoryState()` is fine for tests but loses state between runs. For team use, swap in `httpStateStore()`.
 
-Long-running operations (`createProjects`, `patchProjects`, GKE cluster ops) are polled internally; reconcilers follow the [Alchemy reconciler doctrine](https://v2.alchemy.run/concepts/resource-lifecycle) (single observe → ensure → sync → return flow that converges from any starting state, including adoption).
+Long-running operations (`createProjects`, `patchProjects`, GKE cluster ops, Cloud Run service deploys) are polled internally; reconcilers follow the [Alchemy reconciler doctrine](https://v2.alchemy.run/concepts/resource-lifecycle) (single observe → ensure → sync → return flow that converges from any starting state, including adoption).
 
 ## Resources
 
+### Foundation
 - **`GCP.Project`** — projects under an org or folder, with optional billing-account attach.
 - **`GCP.ApiEnable`** — project-level GCP service enablement.
+
+### Compute
 - **`GCP.Cluster`** — Standard GKE cluster.
 - **`GCP.NodePool`** — node pool attached to a cluster, including accelerator (GPU) configurations.
+
+### Networking
 - **`GCP.Network`** — VPC network.
 - **`GCP.Subnetwork`** — VPC subnetwork.
 - **`GCP.PsaConnection`** — Private Service Access peering for Google managed services.
 - **`GCP.GlobalAddress`** — global IP address (typically used to reserve a PSA range).
 - **`GCP.SharedVpcHost`** / **`GCP.SharedVpcServiceProject`** — Shared VPC enable/attach.
-- **`GCP.ParallelstoreInstance`** — Parallelstore filesystem instance.
+
+### Serverless (Cloud Run v2)
+- **`GCP.Service`** — Cloud Run HTTP service with traffic routing, ingress controls, and IAM.
+- **`GCP.Job`** — Cloud Run batch workload (declarative definition; trigger execution imperatively via `runProjectsLocationsJobs`).
+- **`GCP.serviceIamMember`** / **`GCP.jobIamMember`** — bind `(role, member)` IAM grants on Cloud Run resources. Provider unions all bindings and writes one `setIamPolicy` per target, preserving foreign roles.
+
+### Storage
+- **`GCP.ManagedLustreInstance`** — Managed Lustre filesystem instance.
 
 Each resource's full prop/attribute set is documented as JSDoc on the source.
 
+### Cloud Run example
+
+```ts
+const api = yield* GCP.Service("HelloApi", {
+  project: project.projectId,
+  location: "europe-west4",
+  template: {
+    containers: [{ image: "gcr.io/cloudrun/hello" }],
+  },
+});
+
+// Declarative public access — preferred over `invokerIamDisabled: true`,
+// which bypasses IAM entirely and leaves no audit trail.
+yield* GCP.serviceIamMember(api, "PublicInvoker", {
+  role: "roles/run.invoker",
+  member: "allUsers",
+});
+
+// Batch workload — definition only; execution is imperative.
+const batch = yield* GCP.Job("ProcessBatch", {
+  project: project.projectId,
+  location: "europe-west4",
+  template: {
+    taskCount: 1,
+    template: {
+      maxRetries: 3,
+      containers: [{ image: "europe-west4-docker.pkg.dev/proj/repo/worker:v1" }],
+    },
+  },
+});
+```
+
+Clean type aliases are re-exported from the top level so consumers don't need to import from `@distilled.cloud/gcp` directly: `GCP.RevisionTemplate`, `GCP.Container`, `GCP.TrafficTarget`, `GCP.VpcAccess`, `GCP.NodeSelector`, etc.
+
 ## Adoption
 
 `read` is gated on the alchemy internal labels `alchemy_app` / `alchemy_stage` / `alchemy_id`. Existing GCP resources lacking those labels are returned `Unowned` — the engine refuses to take them over without explicit `--adopt` (or `adopt(true)` on the resource call).
 
+For resources that don't carry labels (Network, Subnetwork), the same `(app, stage, id)` triple is encoded as a sentinel inside `description` and matched on `read`.
+
+## Optimistic concurrency
+
+Resources with server-side fingerprints (Cloud Run Service/Job, Subnetwork) pass the observed `etag`/`fingerprint` through patch and delete calls. A concurrent edit between observe and patch surfaces as `Conflict` rather than silently overwriting.
+
 ## License
 
 Apache-2.0.

package/lib/ArtifactRegistry/Operations.d.ts

@@ -0,0 +1,47 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as ar from "@distilled.cloud/gcp/artifactregistry-v1";
+import type { ScopedPlanStatusSession } from "alchemy/Cli/Cli";
+import * as Effect from "effect/Effect";
+/**
+ * Resolved callable signature of `ar.getProjectsLocationsOperations`.
+ *
+ * `ar.getProjectsLocationsOperations` is itself an
+ * `Effect<callable, never, Credentials | HttpClient>`, so
+ * `Effect.Success` extracts the callable type. Using a derived alias
+ * keeps the helper aligned with the SDK without us hand-writing the
+ * input/output/error union, which would drift if the patch set changes.
+ */
+type GetOperations = Effect.Success<typeof ar.getProjectsLocationsOperations>;
+/**
+ * Build the Artifact Registry long-running-operation polling helper.
+ *
+ * Artifact Registry `Operation`s use the standard
+ * `GoogleLongrunningOperation` shape — doneness is `.done === true`
+ * (NOT `.status === "DONE"` like the GKE Container API and NOT
+ * Sqladmin's tri-state `.status`). Verified at
+ * `vendor/distilled/packages/gcp/src/services/artifactregistry-v1.ts:308–328`.
+ *
+ * Operation names returned by `artifactregistry-v1`
+ * (`createProjectsLocationsRepositories`,
+ * `patchProjectsLocationsRepositories`,
+ * `deleteProjectsLocationsRepositories`) are already fully qualified
+ * (`projects/{p}/locations/{l}/operations/{id}`), so callers pass them
+ * straight through to `getProjectsLocationsOperations` — no qualify
+ * dance needed (unlike Container, which returns bare ids).
+ *
+ * Schedule: exponential 1s → 1.5× growth, capped per-poll at 10s via
+ * `Schedule.either`, then a hard count cap of 60 retries → ~10 min wall
+ * ceiling. Repository CRUD is fast (seconds); the only long-running
+ * case is a delete on a repository with many cached images, where AR
+ * has to GC the underlying blobs.
+ *
+ * The helper is a factory — the caller resolves
+ * `ar.getProjectsLocationsOperations` once at provider construction
+ * and passes the resulting callable here, so we never re-resolve
+ * services on each await.
+ */
+export declare const makeAwaitOperation: (getOperations: GetOperations) => (operationName: string, session: ScopedPlanStatusSession) => Effect.Effect<ar.Operation, ar.GetProjectsLocationsOperationsError | ConfigError | {
+    _tag: "OperationPending";
+}, never>;
+export {};
+//# sourceMappingURL=Operations.d.ts.map

package/lib/ArtifactRegistry/Operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Operations.d.ts","sourceRoot":"","sources":["../../src/ArtifactRegistry/Operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC;;;;;;;;GAQG;AACH,KAAK,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,8BAA8B,CAAC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,kBAAkB,GAAI,eAAe,aAAa;;SAgC3D,CAAC"}

package/lib/ArtifactRegistry/Operations.js

@@ -0,0 +1,47 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+/**
+ * Build the Artifact Registry long-running-operation polling helper.
+ *
+ * Artifact Registry `Operation`s use the standard
+ * `GoogleLongrunningOperation` shape — doneness is `.done === true`
+ * (NOT `.status === "DONE"` like the GKE Container API and NOT
+ * Sqladmin's tri-state `.status`). Verified at
+ * `vendor/distilled/packages/gcp/src/services/artifactregistry-v1.ts:308–328`.
+ *
+ * Operation names returned by `artifactregistry-v1`
+ * (`createProjectsLocationsRepositories`,
+ * `patchProjectsLocationsRepositories`,
+ * `deleteProjectsLocationsRepositories`) are already fully qualified
+ * (`projects/{p}/locations/{l}/operations/{id}`), so callers pass them
+ * straight through to `getProjectsLocationsOperations` — no qualify
+ * dance needed (unlike Container, which returns bare ids).
+ *
+ * Schedule: exponential 1s → 1.5× growth, capped per-poll at 10s via
+ * `Schedule.either`, then a hard count cap of 60 retries → ~10 min wall
+ * ceiling. Repository CRUD is fast (seconds); the only long-running
+ * case is a delete on a repository with many cached images, where AR
+ * has to GC the underlying blobs.
+ *
+ * The helper is a factory — the caller resolves
+ * `ar.getProjectsLocationsOperations` once at provider construction
+ * and passes the resulting callable here, so we never re-resolve
+ * services on each await.
+ */
+export const makeAwaitOperation = (getOperations) => 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(10))), Schedule.both(Schedule.recurs(60)), Schedule.tapOutput(() => session.note(`Waiting for Artifact Registry operation ${operationName}…`))),
+    }));
+    if (op.error) {
+        return yield* new ConfigError({
+            message: `Artifact Registry operation ${operationName} failed: ${op.error.message ?? JSON.stringify(op.error)}`,
+        });
+    }
+    return op;
+});
+//# sourceMappingURL=Operations.js.map

package/lib/ArtifactRegistry/Operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Operations.js","sourceRoot":"","sources":["../../src/ArtifactRegistry/Operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAa5C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,aAA4B,EAAE,EAAE,CACjE,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,EACjB,aAAqB,EACrB,OAAgC;IAEhC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,IAAI,CAC3D,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CACzB,OAAO,CAAC,IAAI,KAAK,IAAI;QACnB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;QACzB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,kBAA2B,EAAE,CAAC,CACvD,EACD,MAAM,CAAC,KAAK,CAAC;QACX,KAAK,EAAE,CAAC,CAAoB,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,KAAK,kBAAkB;QAC/D,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAC3D,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EACtD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAClC,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,CACtB,OAAO,CAAC,IAAI,CACV,2CAA2C,aAAa,GAAG,CAC5D,CACF,CACF;KACF,CAAC,CACH,CAAC;IACF,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,KAAK,CAAC,CAAC,IAAI,WAAW,CAAC;YAC5B,OAAO,EAAE,+BAA+B,aAAa,YACnD,EAAE,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAC7C,EAAE;SACH,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC,CAAC"}

package/lib/ArtifactRegistry/Repository.d.ts

@@ -0,0 +1,263 @@
+import * as ar from "@distilled.cloud/gcp/artifactregistry-v1";
+import { Resource } from "alchemy";
+import * as Provider from "alchemy/Provider";
+import type * as GCP from "../Providers.ts";
+import type { ArtifactRegistryFormat, ArtifactRegistryMode } from "./Types.ts";
+/**
+ * Docker remote upstream — either a Google-known public repository
+ * (today: Docker Hub) or an arbitrary HTTPS Docker registry like
+ * `https://nvcr.io` or `https://quay.io`. Discriminated union — the
+ * server rejects bodies that supply both. Matches
+ * `ar.DockerRepository`.
+ *
+ * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#DockerRepository
+ */
+export type ArtifactRegistryDockerUpstream = {
+    /**
+     * One of Artifact Registry's built-in public-repository
+     * presets. Today only `DOCKER_HUB` is meaningful for the docker
+     * format. The string-tail is left open for forward compat with
+     * any future presets the server adds.
+     */
+    publicRepository: "DOCKER_HUB" | (string & {});
+    customRepository?: never;
+} | {
+    /**
+     * Arbitrary HTTPS Docker upstream — `https://nvcr.io`,
+     * `https://quay.io`, a self-hosted Harbor, etc. The server
+     * trims any path / pulls the manifest endpoint conventionally.
+     */
+    customRepository: {
+        uri: string;
+    };
+    publicRepository?: never;
+};
+/**
+ * A Google Artifact Registry **Repository** of `format: "DOCKER"` —
+ * either a standard upload-target (`STANDARD_REPOSITORY`) for the
+ * project's own container builds, or a pull-through cache
+ * (`REMOTE_REPOSITORY`) pointing at Docker Hub or a custom upstream
+ * like `nvcr.io`.
+ *
+ * **Resource model.** A repository lives at
+ * `projects/{project}/locations/{location}/repositories/{name}`.
+ * Format and mode are immutable; the upstream config for a remote
+ * repository is also immutable on the GCP side (any change triggers a
+ * replace).
+ *
+ * **Lifecycle.** observe → ensure (create LRO; retry on the
+ * "API not yet enabled" 403 propagation race) → sync (patch
+ * description, labels, dockerConfig, cleanup policies via
+ * `updateMask`) → return. Mirrors `Sqladmin/Instance.ts` /
+ * `Run/Service.ts`.
+ *
+ * **Replace triggers.** `project`, `location`, `name`, `format`,
+ * `mode`, `kmsKeyName`, and any change inside `remoteRepositoryConfig`.
+ *
+ * **Adoption.** Label-gated via `alchemy_*` labels. A repository
+ * whose `labels` lack our keys is wrapped in `Unowned(attrs)` from
+ * `read`, forcing `--adopt` before takeover.
+ *
+ * @example Standard Docker repo for the project's own builds
+ * ```typescript
+ * const apps = yield* GCP.ArtifactRegistryRepository("Apps", {
+ *   project: project.projectId,
+ *   location: "europe-west4",
+ *   format: "DOCKER",
+ *   description: "App images built by CI",
+ * });
+ * ```
+ *
+ * @example Pull-through cache for Docker Hub
+ * ```typescript
+ * yield* GCP.ArtifactRegistryRepository("DockerHubMirror", {
+ *   project: project.projectId,
+ *   location: "europe-west4",
+ *   format: "DOCKER",
+ *   mode: "REMOTE_REPOSITORY",
+ *   remoteRepositoryConfig: {
+ *     description: "Pull-through cache for docker.io",
+ *     dockerRepository: { publicRepository: "DOCKER_HUB" },
+ *   },
+ * });
+ * ```
+ *
+ * @example Pull-through cache for nvcr.io
+ * ```typescript
+ * yield* GCP.ArtifactRegistryRepository("NvcrMirror", {
+ *   project: project.projectId,
+ *   location: "europe-west4",
+ *   format: "DOCKER",
+ *   mode: "REMOTE_REPOSITORY",
+ *   remoteRepositoryConfig: {
+ *     description: "Pull-through cache for nvcr.io",
+ *     dockerRepository: { customRepository: { uri: "https://nvcr.io" } },
+ *   },
+ * });
+ * ```
+ *
+ * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#Repository
+ */
+export type ArtifactRegistryRepositoryProps = {
+    /**
+     * GCP project ID hosting the repository. Immutable — replace if
+     * changed.
+     * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#Repository
+     */
+    project: string;
+    /**
+     * Artifact Registry location (e.g. `europe-west4`). Regional only —
+     * multi-region is not supported by this resource. Immutable.
+     * @see https://cloud.google.com/artifact-registry/docs/repositories/repo-locations
+     */
+    location: string;
+    /**
+     * Repository short name (the trailing path segment under
+     * `…/repositories/`). Defaults to a sanitised
+     * `createPhysicalName({ id, lowercase: true, maxLength: 63 })`.
+     * Lowercase letters/digits/hyphens; start with a letter or digit;
+     * 1–63 chars. Immutable — replace if changed.
+     * @see https://cloud.google.com/artifact-registry/docs/repositories/create-repos#create
+     */
+    name?: string;
+    /**
+     * Package format. Today the provider exercises only `DOCKER`; other
+     * formats are reachable via the open-tail union but un-tested.
+     * Immutable — replace if changed.
+     * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#Format
+     */
+    format: ArtifactRegistryFormat;
+    /**
+     * Repository mode. Defaults to `STANDARD_REPOSITORY`. Set to
+     * `REMOTE_REPOSITORY` to act as a pull-through cache for an upstream
+     * Docker registry; in that case `remoteRepositoryConfig` is
+     * required. Immutable — replace if changed (GCP does not allow
+     * flipping a repository between modes).
+     * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#Mode
+     */
+    mode?: ArtifactRegistryMode;
+    /**
+     * Human-readable description. Mutable via `patch` with
+     * `updateMask=description`.
+     * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#Repository.FIELDS.description
+     */
+    description?: string;
+    /**
+     * Resource labels. Alchemy internal labels (`alchemy_app`,
+     * `alchemy_stage`, `alchemy_id`) are merged on top automatically.
+     * Mutable via `patch` with `updateMask=labels`.
+     * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#Repository.FIELDS.labels
+     */
+    labels?: Record<string, string>;
+    /**
+     * Customer-managed encryption key, fully-qualified
+     * (`projects/{p}/locations/{l}/keyRings/{kr}/cryptoKeys/{k}`).
+     * Immutable on the GCP side — we surface that as a replace trigger.
+     * Requires the AR service agent to hold
+     * `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the key.
+     * @see https://cloud.google.com/artifact-registry/docs/cmek
+     */
+    kmsKeyName?: string;
+    /**
+     * Docker-format repository configuration. Mutable via `patch` with
+     * `updateMask=dockerConfig`.
+     * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#DockerRepositoryConfig
+     */
+    dockerConfig?: {
+        /**
+         * When true, image tags inside this repository cannot be moved or
+         * deleted once written. Useful for supply-chain hardening.
+         */
+        immutableTags?: boolean;
+    };
+    /**
+     * Remote-repository configuration. Required (and only meaningful)
+     * when `mode === "REMOTE_REPOSITORY"`. Immutable on the GCP side —
+     * any change to fields under this object triggers a replace.
+     * @see https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories#RemoteRepositoryConfig
+     */
+    remoteRepositoryConfig?: {
+        /**
+         * Description of the remote source (distinct from the top-level
+         * `description`).
+         */
+        description?: string;
+        /** Docker upstream — public preset or arbitrary HTTPS URI. */
+        dockerRepository?: ArtifactRegistryDockerUpstream;
+        /**
+         * If true, AR skips the create-time HEAD request against the
+         * upstream. Useful for upstreams that gate unauthenticated probes
+         * (private nvcr.io paths, etc.).
+         */
+        disableUpstreamValidation?: boolean;
+        /**
+         * Credentials for authenticated upstreams — supply a Secret
+         * Manager version reference for the password rather than the
+         * cleartext value.
+         */
+        upstreamCredentials?: {
+            usernamePasswordCredentials?: {
+                username?: string;
+                /**
+                 * Secret Manager secret version path:
+                 * `projects/{p}/secrets/{s}/versions/{v}`.
+                 */
+                passwordSecretVersion?: string;
+            };
+        };
+    };
+    /**
+     * Cleanup policies — map of policy ID → policy spec. Pass-through
+     * to the API today; the policy types are accepted via the
+     * distilled SDK's `CleanupPolicy` shape but not specifically
+     * validated by this provider. Mutable via `patch` with
+     * `updateMask=cleanupPolicies`.
+     * @see https://cloud.google.com/artifact-registry/docs/repositories/cleanup-policy
+     */
+    cleanupPolicies?: Record<string, ar.CleanupPolicy>;
+    /**
+     * If true, cleanup policies are evaluated and reported but no
+     * versions are actually deleted. Mutable via `patch` with
+     * `updateMask=cleanupPolicyDryRun`.
+     * @see https://cloud.google.com/artifact-registry/docs/repositories/cleanup-policy#test
+     */
+    cleanupPolicyDryRun?: boolean;
+};
+export type ArtifactRegistryRepositoryAttributes = {
+    /** Bare repository name (no `projects/.../repositories/` prefix). */
+    name: string;
+    /**
+     * Server-side fully-qualified name:
+     * `projects/{project}/locations/{location}/repositories/{name}`.
+     */
+    fullyQualifiedName: string;
+    /** GCP project ID. */
+    project: string;
+    /** Region. */
+    location: string;
+    /** Echoed format (e.g. `DOCKER`). */
+    format: string;
+    /** Echoed mode (e.g. `STANDARD_REPOSITORY`). */
+    mode: string;
+    /**
+     * Repository endpoint (e.g. `europe-west4-docker.pkg.dev/proj/repo`)
+     * — the host:path you'd `docker pull` from. Populated by the server.
+     */
+    registryUri: string | undefined;
+    /** Total stored size in bytes, server-reported. */
+    sizeBytes: string | undefined;
+    /** PZS compliance flag. */
+    satisfiesPzs: boolean | undefined;
+    /** PZI compliance flag. */
+    satisfiesPzi: boolean | undefined;
+    /** Labels currently set, including alchemy internals. */
+    labels: Record<string, string>;
+    /** RFC3339 create timestamp. */
+    createTime: string;
+    /** RFC3339 last-update timestamp. */
+    updateTime: string;
+};
+export type ArtifactRegistryRepository = Resource<"GCP.ArtifactRegistryRepository", ArtifactRegistryRepositoryProps, ArtifactRegistryRepositoryAttributes, never, GCP.Providers>;
+export declare const ArtifactRegistryRepository: import("alchemy").ResourceClass<ArtifactRegistryRepository>;
+export declare const ArtifactRegistryRepositoryProvider: () => import("effect/Layer").Layer<Provider.Provider<ArtifactRegistryRepository>, never, import("effect/unstable/http/HttpClient").HttpClient | import("alchemy").Stage | import("alchemy").Stack | import("@distilled.cloud/gcp").Credentials>;
+//# sourceMappingURL=Repository.d.ts.map

package/lib/ArtifactRegistry/Repository.d.ts.map

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