@intentius/chant-lexicon-azure 0.124.46 → 0.124.48

package/README.md

@@ -10,6 +10,14 @@ npm install --save-dev @intentius/chant @intentius/chant-lexicon-azure
 
 **[Documentation →](https://intentius.io/chant/lexicons/azure/)**
 
+## Lifecycle
+
+chant marks what it owns with ARM tags (`src/ownership.ts`): `chant-managed-by`, `chant-stack` and `chant-env`. Azure tag keys can't hold `/`, so these differ from the label keys k8s and gcp use.
+
+- `chant lifecycle diff <env> --live` and `chant lifecycle plan <env>` read the resource group live and compare it with the built template, keyed by those tags.
+- `azApply`, the Op activity, and `arm-deploy`, the component step, apply the template resource by resource with ARM PUTs into one resource group, rather than through `az deployment`. `AZURE_ENDPOINT_URL` points them at an emulator such as floci-az.
+- With `prune`, the applier deletes chant-owned resources in the group that the template no longer declares, and nothing it doesn't own.
+
 ## Related Packages
 
 | Package | Role |

package/dist/components/acr-backend.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The azure lexicon's registry login for core's `publish-image` (#3142): ACR,
+ * through `az acr login`. Core owns load, tag, push and the digest read-back;
+ * this only authenticates the local docker client.
+ */
+import type { RegistryLoginBackend } from "@intentius/chant/components/verbs/publish-image";
+import { type ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+export declare function createAcrRegistryBackend(runner?: ProcessRunner): RegistryLoginBackend;
+/** The ACR backend the azure plugin contributes, over the real process runner. */
+export declare const acrRegistryBackend: RegistryLoginBackend;
+//# sourceMappingURL=acr-backend.d.ts.map

package/dist/components/acr-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acr-backend.d.ts","sourceRoot":"","sources":["../../src/components/acr-backend.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iDAAiD,CAAC;AAC5F,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,kDAAkD,CAAC;AAK/G,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,oBAAoB,CAUrF;AAED,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,EAAE,oBAAiD,CAAC"}

package/dist/components/acr-backend.js

@@ -0,0 +1,17 @@
+import { defaultProcessRunner, q } from "@intentius/chant/components/verbs/process-runner";
+/** `<name>.azurecr.io` (also the sovereign-cloud suffixes). */
+const ACR_HOST = /^([a-z0-9]+)\.azurecr\.(io|cn|us)$/i;
+export function createAcrRegistryBackend(runner) {
+    return {
+        name: "acr",
+        matches: (registry) => ACR_HOST.test(registry),
+        async login(registry) {
+            const m = ACR_HOST.exec(registry);
+            if (!m)
+                throw new Error(`acr login: "${registry}" is not an Azure Container Registry host (<name>.azurecr.io)`);
+            await (runner ?? defaultProcessRunner()).run(`az acr login --name ${q(m[1])}`);
+        },
+    };
+}
+/** The ACR backend the azure plugin contributes, over the real process runner. */
+export const acrRegistryBackend = createAcrRegistryBackend();

package/dist/components/blob-backend.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The azure lexicon's storage backend for core's `publish-artifact` (#4408):
+ * Azure Blob Storage through `az storage blob upload`. Core owns the content
+ * digest and the object URI; this only uploads.
+ */
+import type { ArtifactStorageBackend } from "@intentius/chant/components/verbs/publish-artifact";
+import { type ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+export declare function createAzureBlobStorageBackend(runner?: ProcessRunner): ArtifactStorageBackend;
+/** The Blob backend the azure plugin contributes, over the real process runner. */
+export declare const azureBlobStorageBackend: ArtifactStorageBackend;
+//# sourceMappingURL=blob-backend.d.ts.map

package/dist/components/blob-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-backend.d.ts","sourceRoot":"","sources":["../../src/components/blob-backend.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oDAAoD,CAAC;AACjG,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,kDAAkD,CAAC;AAK/G,wBAAgB,6BAA6B,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,sBAAsB,CAc5F;AAED,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,EAAE,sBAAwD,CAAC"}

package/dist/components/blob-backend.js

@@ -0,0 +1,18 @@
+import { defaultProcessRunner, q } from "@intentius/chant/components/verbs/process-runner";
+/** `https://<account>.blob.core.windows.net/<container>/<blob path>` (also the sovereign-cloud suffixes). */
+const BLOB_URI = /^https:\/\/([a-z0-9]+)\.blob\.core\.(windows\.net|chinacloudapi\.cn|usgovcloudapi\.net)\/([^/]+)\/(.+)$/i;
+export function createAzureBlobStorageBackend(runner) {
+    return {
+        name: "azure-blob",
+        matches: (uri) => /^https:\/\/[a-z0-9]+\.blob\.core\./i.test(uri),
+        async upload({ from, to }) {
+            const m = BLOB_URI.exec(to);
+            if (!m) {
+                throw new Error(`azure-blob upload: "${to}" is not a blob URI (https://<account>.blob.core.windows.net/<container>/<path>)`);
+            }
+            await (runner ?? defaultProcessRunner()).run(`az storage blob upload --account-name ${q(m[1])} --container-name ${q(m[3])} --name ${q(m[4])} --file ${q(from)} --overwrite --auth-mode login`);
+        },
+    };
+}
+/** The Blob backend the azure plugin contributes, over the real process runner. */
+export const azureBlobStorageBackend = createAzureBlobStorageBackend();

package/dist/components/builders.d.ts

@@ -0,0 +1,6 @@
+import type { ArmDeployInput } from "./arm-deploy.js";
+import type { WaitContainerAppInput } from "./wait-azure.js";
+export declare const armDeploy: (input: ArmDeployInput) => import("@intentius/chant/components").Step;
+export declare const waitForDeployment: (input: import("./wait-azure.js").TargetInput) => import("@intentius/chant/components").Step;
+export declare const waitContainerApp: (input: WaitContainerAppInput) => import("@intentius/chant/components").Step;
+//# sourceMappingURL=builders.d.ts.map

package/dist/components/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/components/builders.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAA0B,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAElF,eAAO,MAAM,SAAS,uEAAqC,CAAC;AAC5D,eAAO,MAAM,iBAAiB,2FAAsD,CAAC;AACrF,eAAO,MAAM,gBAAgB,8EAAoD,CAAC"}

package/dist/components/builders.js

@@ -0,0 +1,11 @@
+/**
+ * Typed step-builders for the azure lexicon's verbs (#3142), the same sugar the
+ * aws lexicon offers. `armDeploy({ template })` is exactly
+ * `{ kind: "arm-deploy", template }`, checked against the capability's input.
+ * `publishImage` is core's verb; azure contributes only the ACR login, chosen
+ * by the registry host or `$env.publish.backend`.
+ */
+import { step } from "@intentius/chant/components";
+export const armDeploy = step("arm-deploy");
+export const waitForDeployment = step("wait-for-deployment");
+export const waitContainerApp = step("wait-container-app");

package/dist/components/capability-plugin.d.ts

@@ -1,6 +1,7 @@
 import { type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
 export declare const AZURE_VERB_FAMILIES: {
     readonly apply: readonly ["arm-deploy"];
+    readonly waitVerify: readonly ["wait-for-deployment", "wait-container-app"];
 };
 export declare const azureCapabilityPlugin: CapabilityPlugin;
 //# sourceMappingURL=capability-plugin.d.ts.map

package/dist/components/capability-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAGzG,eAAO,MAAM,mBAAmB;aAC9B,KAAK,YAAG,YAAY;CACZ,CAAC;AAEX,eAAO,MAAM,qBAAqB,EAAE,gBAWnC,CAAC"}
+{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAMzG,eAAO,MAAM,mBAAmB;aAC9B,KAAK,YAAG,YAAY;aACpB,UAAU,YAAG,qBAAqB,EAAE,oBAAoB;CAEhD,CAAC;AAEX,eAAO,MAAM,qBAAqB,EAAE,gBAqBnC,CAAC"}

package/dist/components/capability-plugin.js

@@ -1,7 +1,12 @@
 import { ownPackageVersion } from "@intentius/chant/components/capability-plugin";
 import { armDeployCapability } from "./arm-deploy.js";
+import { waitForDeploymentCapability, waitContainerAppCapability } from "./wait-azure.js";
+import { acrRegistryBackend } from "./acr-backend.js";
+import { azureBlobStorageBackend } from "./blob-backend.js";
 export const AZURE_VERB_FAMILIES = {
     apply: ["arm-deploy"],
+    waitVerify: ["wait-for-deployment", "wait-container-app"],
+    // `publish-image` is core's verb; azure contributes the "acr" registry login backend.
 };
 export const azureCapabilityPlugin = {
     name: "azure",
@@ -9,7 +14,17 @@ export const azureCapabilityPlugin = {
         return ownPackageVersion(import.meta.url);
     },
     capabilities() {
-        return [armDeployCapability];
+        return [
+            armDeployCapability,
+            waitForDeploymentCapability,
+            waitContainerAppCapability,
+        ];
+    },
+    registryBackends() {
+        return [acrRegistryBackend];
+    },
+    storageBackends() {
+        return [azureBlobStorageBackend];
     },
     families() {
         return AZURE_VERB_FAMILIES;

package/dist/components/index.d.ts

@@ -1,3 +1,7 @@
 export { azureCapabilityPlugin, AZURE_VERB_FAMILIES } from "./capability-plugin.js";
 export { armDeployCapability, createArmDeployCapability, ArmDeployPlanMovedError, type ArmDeployInput, type ArmDeployOutput, type ArmDeployPlanArtifact, } from "./arm-deploy.js";
+export * from "./wait-azure.js";
+export * from "./builders.js";
+export { createAcrRegistryBackend, acrRegistryBackend } from "./acr-backend.js";
+export { createAzureBlobStorageBackend, azureBlobStorageBackend } from "./blob-backend.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/components/index.js

@@ -1,2 +1,6 @@
 export { azureCapabilityPlugin, AZURE_VERB_FAMILIES } from "./capability-plugin.js";
 export { armDeployCapability, createArmDeployCapability, ArmDeployPlanMovedError, } from "./arm-deploy.js";
+export * from "./wait-azure.js";
+export * from "./builders.js";
+export { createAcrRegistryBackend, acrRegistryBackend } from "./acr-backend.js";
+export { createAzureBlobStorageBackend, azureBlobStorageBackend } from "./blob-backend.js";

package/dist/components/wait-azure.d.ts

@@ -0,0 +1,59 @@
+/**
+ * wait / verify family, azure members (#3142): `wait-for-deployment` (every
+ * resource of a group reaches an ARM terminal provisioning state) and
+ * `wait-container-app` (a Container App serves its latest revision). Both
+ * poll ARM through the read client, so a test or floci-az swaps `http`. A wait
+ * is a read-only observation: neither declares a rollback.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import type { AzHttp } from "../op/activities/az-apply.js";
+export interface AzureWaitOptions {
+    http?: AzHttp;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export interface TargetInput {
+    /** The resource group. Default: the component's name. */
+    resourceGroup?: string;
+    /** ARM endpoint. Default: `AZURE_ENDPOINT_URL`, else real Azure. */
+    endpoint?: string;
+    /** Subscription id. Default: `AZURE_SUBSCRIPTION_ID`, else floci-az's local subscription. */
+    subscriptionId?: string;
+    /** Poll interval in ms. Default: 10000. */
+    intervalMs?: number;
+    /** Overall timeout in ms. Default: 10 minutes. */
+    timeoutMs?: number;
+}
+export type WaitForDeploymentInput = TargetInput;
+export interface WaitForDeploymentOutput {
+    /** Resources of the group, each with the state it ended in. */
+    resources: Array<{
+        type: string;
+        name: string;
+        state: string;
+    }>;
+}
+/**
+ * Poll the group until no resource is still provisioning. Throws when one ends
+ * `Failed` or `Canceled`, or when the timeout passes first. A resource whose
+ * body carries no `provisioningState` (some types do not) counts as settled.
+ */
+export declare function createWaitForDeploymentCapability(options?: AzureWaitOptions): Capability<WaitForDeploymentInput, WaitForDeploymentOutput>;
+export declare const waitForDeploymentCapability: Capability<WaitForDeploymentInput, WaitForDeploymentOutput>;
+export interface WaitContainerAppInput extends TargetInput {
+    /** The Container App's name. */
+    app: string;
+}
+export interface WaitContainerAppOutput {
+    /** The revision serving traffic once the app is steady. */
+    revision: string;
+    /** The app's FQDN, when it has ingress. */
+    fqdn?: string;
+}
+/**
+ * Poll a Container App until provisioning succeeded and its latest revision is
+ * the latest ready one. A rollout that fails provisioning throws.
+ */
+export declare function createWaitContainerAppCapability(options?: AzureWaitOptions): Capability<WaitContainerAppInput, WaitContainerAppOutput>;
+export declare const waitContainerAppCapability: Capability<WaitContainerAppInput, WaitContainerAppOutput>;
+//# sourceMappingURL=wait-azure.d.ts.map

package/dist/components/wait-azure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-azure.d.ts","sourceRoot":"","sources":["../../src/components/wait-azure.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAOxD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoBD,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAEjD,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,GAAE,gBAAqB,GAC7B,UAAU,CAAC,sBAAsB,EAAE,uBAAuB,CAAC,CA+B7D;AAED,eAAO,MAAM,2BAA2B,EAAE,UAAU,CAAC,sBAAsB,EAAE,uBAAuB,CAC/D,CAAC;AAItC,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,gBAAqB,GAC7B,UAAU,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAkC3D;AAED,eAAO,MAAM,0BAA0B,EAAE,UAAU,CAAC,qBAAqB,EAAE,sBAAsB,CAC7D,CAAC"}

package/dist/components/wait-azure.js

@@ -0,0 +1,106 @@
+import { getResource, getResourceById, isNotFound, listResources } from "../api/read-client.js";
+const DEFAULT_INTERVAL_MS = 10000;
+const DEFAULT_TIMEOUT_MS = 10 * 60000;
+/** ARM provisioning states that will not change without a new request. */
+const TERMINAL = new Set(["Succeeded", "Failed", "Canceled"]);
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function client(input, component, options) {
+    const endpoint = input.endpoint ?? process.env.AZURE_ENDPOINT_URL;
+    const subscriptionId = input.subscriptionId ?? process.env.AZURE_SUBSCRIPTION_ID;
+    return {
+        resourceGroup: input.resourceGroup ?? component,
+        ...(endpoint ? { endpoint } : {}),
+        ...(subscriptionId ? { subscriptionId } : {}),
+        ...(options.http ? { http: options.http } : {}),
+    };
+}
+function provisioningState(body) {
+    const s = body.properties?.provisioningState;
+    return typeof s === "string" ? s : undefined;
+}
+/**
+ * Poll the group until no resource is still provisioning. Throws when one ends
+ * `Failed` or `Canceled`, or when the timeout passes first. A resource whose
+ * body carries no `provisioningState` (some types do not) counts as settled.
+ */
+export function createWaitForDeploymentCapability(options = {}) {
+    const sleep = options.sleep ?? realSleep;
+    const now = options.now ?? Date.now;
+    return {
+        kind: "wait-for-deployment",
+        async run(ctx, input) {
+            const read = client(input, ctx.component, options);
+            const interval = input.intervalMs ?? DEFAULT_INTERVAL_MS;
+            const deadline = now() + (input.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            while (true) {
+                const listed = await listResources(read);
+                const resources = [];
+                for (const item of listed) {
+                    const body = item.id ? await getResourceById(read, item.id) : item;
+                    resources.push({
+                        type: String(item.type ?? ""),
+                        name: String(item.name ?? ""),
+                        state: provisioningState(body) ?? "Succeeded",
+                    });
+                }
+                const bad = resources.find((r) => r.state === "Failed" || r.state === "Canceled");
+                if (bad)
+                    throw new Error(`wait-for-deployment "${read.resourceGroup}": ${bad.type}/${bad.name} ended ${bad.state}`);
+                if (resources.every((r) => TERMINAL.has(r.state)))
+                    return { resources };
+                if (now() > deadline) {
+                    const pending = resources.filter((r) => !TERMINAL.has(r.state)).map((r) => `${r.name} (${r.state})`).join(", ");
+                    throw new Error(`wait-for-deployment "${read.resourceGroup}" timed out; still provisioning: ${pending}`);
+                }
+                await sleep(interval);
+            }
+        },
+    };
+}
+export const waitForDeploymentCapability = createWaitForDeploymentCapability();
+/**
+ * Poll a Container App until provisioning succeeded and its latest revision is
+ * the latest ready one. A rollout that fails provisioning throws.
+ */
+export function createWaitContainerAppCapability(options = {}) {
+    const sleep = options.sleep ?? realSleep;
+    const now = options.now ?? Date.now;
+    return {
+        kind: "wait-container-app",
+        async run(ctx, input) {
+            const read = client(input, ctx.component, options);
+            const interval = input.intervalMs ?? DEFAULT_INTERVAL_MS;
+            const deadline = now() + (input.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            while (true) {
+                let state = "NotFound";
+                let ready = false;
+                let revision = "";
+                let fqdn;
+                try {
+                    const body = await getResource(read, "Microsoft.App/containerApps", input.app);
+                    const props = body.properties ?? {};
+                    state = provisioningState(body) ?? "Unknown";
+                    const latest = typeof props.latestRevisionName === "string" ? props.latestRevisionName : undefined;
+                    const latestReady = typeof props.latestReadyRevisionName === "string" ? props.latestReadyRevisionName : undefined;
+                    revision = latestReady ?? latest ?? "";
+                    ready = state === "Succeeded" && (latest === undefined || latest === latestReady);
+                    const ingress = props.configuration?.ingress;
+                    if (typeof ingress?.fqdn === "string")
+                        fqdn = ingress.fqdn;
+                }
+                catch (err) {
+                    if (!isNotFound(err))
+                        throw err;
+                }
+                if (state === "Failed" || state === "Canceled")
+                    throw new Error(`wait-container-app "${input.app}" ended ${state}`);
+                if (ready)
+                    return { revision, ...(fqdn ? { fqdn } : {}) };
+                if (now() > deadline)
+                    throw new Error(`wait-container-app "${input.app}" timed out in state ${state}`);
+                await sleep(interval);
+            }
+        },
+    };
+}
+export const waitContainerAppCapability = createWaitContainerAppCapability();

package/dist/describe-stack-status.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deploy-unit status for Azure (#3142, the #1495 seam). An `arm-deploy` unit is
+ * its resource group. It is present when the group holds chant-owned
+ * resources (the ownership tags `arm-deploy` stamps), and healthy when every
+ * one of them reports a `Succeeded` provisioning state. A read that cannot
+ * happen (no credentials, ARM unreachable) is indeterminate (`null`), never a
+ * confident absence; a group ARM says does not exist is `present: false`.
+ */
+import type { StackStatusObservation } from "@intentius/chant/lexicon";
+import { type AzureReadClientOptions } from "./api/read-client.js";
+export declare function describeStackStatus(options: {
+    environment: string;
+    stack: string;
+}, read?: Partial<AzureReadClientOptions>): Promise<StackStatusObservation | null>;
+//# sourceMappingURL=describe-stack-status.d.ts.map

package/dist/describe-stack-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-stack-status.d.ts","sourceRoot":"","sources":["../src/describe-stack-status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAA8C,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG5G,wBAAsB,mBAAmB,CACvC,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAC/C,IAAI,GAAE,OAAO,CAAC,sBAAsB,CAAM,GACzC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CA2BxC"}

package/dist/describe-stack-status.js

@@ -0,0 +1,33 @@
+import { getResourceById, isNotFound, listResources } from "./api/read-client.js";
+import { isChantOwned } from "./op/activities/az-apply.js";
+export async function describeStackStatus(options, read = {}) {
+    const client = {
+        ...(process.env.AZURE_ENDPOINT_URL ? { endpoint: process.env.AZURE_ENDPOINT_URL } : {}),
+        ...(process.env.AZURE_SUBSCRIPTION_ID ? { subscriptionId: process.env.AZURE_SUBSCRIPTION_ID } : {}),
+        ...read,
+        resourceGroup: options.stack,
+    };
+    try {
+        const owned = (await listResources(client)).filter((r) => isChantOwned(r.tags));
+        if (owned.length === 0)
+            return { stack: options.stack, present: false };
+        const states = [];
+        for (const item of owned) {
+            const body = item.id ? await getResourceById(client, item.id) : item;
+            const s = body.properties?.provisioningState;
+            states.push(typeof s === "string" ? s : "Succeeded");
+        }
+        const ok = states.filter((s) => s === "Succeeded").length;
+        return {
+            stack: options.stack,
+            present: true,
+            status: `${ok}/${states.length} resources succeeded`,
+            healthy: ok === states.length,
+        };
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return { stack: options.stack, present: false };
+        return null;
+    }
+}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "d99147e1901c90e5697d439240fafed5f98c89812732ed93e073acb6ff0c0d44",
+    "manifest.json": "369520efc14abc28045333753c2ae150e635a0bece0da521edf7b11cb58ca934",
     "meta.json": "d2521221ed616d882ded4296f0071685bd74e4b645d55dabc9685733c37dc419",
     "types/index.d.ts": "29631032bda9533849178968290e65d72250eab0b8bab424f2d9ef9b4e8546a4",
     "rules/hardcoded-location.ts": "0b895449c8c94066e81721c46be24249231029fe13b471477456df5c4e45b8bf",
@@ -37,5 +37,5 @@
     "skills/chant-azure-patterns.md": "2d8cb8bbeda73b695856cec4ddaf5b3a0efce76e4ee6e3cf14b90ca69dee5757",
     "skills/chant-azure-aks.md": "2d4e0098c1a22b54ffadd410564d9df0f3a04cb4eb7c6261f20ae33106e7aca8"
   },
-  "composite": "bea3406d9505353c387f90e59b8afdd477ca096e5d2ec3c67c57b7855335f4ed"
+  "composite": "e1f5a1afb2dfc2d52424da55d29e2c1868423c488d7987dfb81c8e448d8ef730"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "azure",
-  "version": "0.124.46",
+  "version": "0.124.48",
   "chantVersion": ">=0.1.0",
   "namespace": "Azure",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,0BAA0B,CAAC;AA2B5E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,aA8dzB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,0BAA0B,CAAC;AA2B5E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,aAoezB,CAAC"}

package/dist/plugin.js

@@ -442,6 +442,11 @@ export const tags = defaultTags([
         const { packageLexicon } = await import("./codegen/package.js");
         await packageLexicon(opts);
     },
+    /** Deploy-unit status for `arm-deploy`'s resource group (#3142). */
+    async describeStackStatus(options) {
+        const { describeStackStatus } = await import("./describe-stack-status.js");
+        return describeStackStatus(options);
+    },
     async describeResources(options) {
         const { describeResources } = await import("./describe-resources.js");
         return describeResources(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-azure",
-  "version": "0.124.46",
+  "version": "0.124.48",
   "description": "Azure lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -79,6 +79,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.46"
+    "@intentius/chant": "^0.124.48"
   }
 }

package/src/components/acr-backend.ts

@@ -0,0 +1,25 @@
+/**
+ * The azure lexicon's registry login for core's `publish-image` (#3142): ACR,
+ * through `az acr login`. Core owns load, tag, push and the digest read-back;
+ * this only authenticates the local docker client.
+ */
+import type { RegistryLoginBackend } from "@intentius/chant/components/verbs/publish-image";
+import { defaultProcessRunner, q, type ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+
+/** `<name>.azurecr.io` (also the sovereign-cloud suffixes). */
+const ACR_HOST = /^([a-z0-9]+)\.azurecr\.(io|cn|us)$/i;
+
+export function createAcrRegistryBackend(runner?: ProcessRunner): RegistryLoginBackend {
+  return {
+    name: "acr",
+    matches: (registry) => ACR_HOST.test(registry),
+    async login(registry) {
+      const m = ACR_HOST.exec(registry);
+      if (!m) throw new Error(`acr login: "${registry}" is not an Azure Container Registry host (<name>.azurecr.io)`);
+      await (runner ?? defaultProcessRunner()).run(`az acr login --name ${q(m[1]!)}`);
+    },
+  };
+}
+
+/** The ACR backend the azure plugin contributes, over the real process runner. */
+export const acrRegistryBackend: RegistryLoginBackend = createAcrRegistryBackend();

package/src/components/blob-backend.ts

@@ -0,0 +1,29 @@
+/**
+ * The azure lexicon's storage backend for core's `publish-artifact` (#4408):
+ * Azure Blob Storage through `az storage blob upload`. Core owns the content
+ * digest and the object URI; this only uploads.
+ */
+import type { ArtifactStorageBackend } from "@intentius/chant/components/verbs/publish-artifact";
+import { defaultProcessRunner, q, type ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+
+/** `https://<account>.blob.core.windows.net/<container>/<blob path>` (also the sovereign-cloud suffixes). */
+const BLOB_URI = /^https:\/\/([a-z0-9]+)\.blob\.core\.(windows\.net|chinacloudapi\.cn|usgovcloudapi\.net)\/([^/]+)\/(.+)$/i;
+
+export function createAzureBlobStorageBackend(runner?: ProcessRunner): ArtifactStorageBackend {
+  return {
+    name: "azure-blob",
+    matches: (uri) => /^https:\/\/[a-z0-9]+\.blob\.core\./i.test(uri),
+    async upload({ from, to }) {
+      const m = BLOB_URI.exec(to);
+      if (!m) {
+        throw new Error(`azure-blob upload: "${to}" is not a blob URI (https://<account>.blob.core.windows.net/<container>/<path>)`);
+      }
+      await (runner ?? defaultProcessRunner()).run(
+        `az storage blob upload --account-name ${q(m[1]!)} --container-name ${q(m[3]!)} --name ${q(m[4]!)} --file ${q(from)} --overwrite --auth-mode login`,
+      );
+    },
+  };
+}
+
+/** The Blob backend the azure plugin contributes, over the real process runner. */
+export const azureBlobStorageBackend: ArtifactStorageBackend = createAzureBlobStorageBackend();

package/src/components/builders.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed step-builders for the azure lexicon's verbs (#3142), the same sugar the
+ * aws lexicon offers. `armDeploy({ template })` is exactly
+ * `{ kind: "arm-deploy", template }`, checked against the capability's input.
+ * `publishImage` is core's verb; azure contributes only the ACR login, chosen
+ * by the registry host or `$env.publish.backend`.
+ */
+import { step } from "@intentius/chant/components";
+import type { ArmDeployInput } from "./arm-deploy";
+import type { WaitForDeploymentInput, WaitContainerAppInput } from "./wait-azure";
+
+export const armDeploy = step<ArmDeployInput>("arm-deploy");
+export const waitForDeployment = step<WaitForDeploymentInput>("wait-for-deployment");
+export const waitContainerApp = step<WaitContainerAppInput>("wait-container-app");

package/src/components/capability-plugin.ts

@@ -7,9 +7,14 @@
 import type { Capability } from "@intentius/chant/components/capability";
 import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
 import { armDeployCapability } from "./arm-deploy";
+import { waitForDeploymentCapability, waitContainerAppCapability } from "./wait-azure";
+import { acrRegistryBackend } from "./acr-backend";
+import { azureBlobStorageBackend } from "./blob-backend";
 
 export const AZURE_VERB_FAMILIES = {
   apply: ["arm-deploy"],
+  waitVerify: ["wait-for-deployment", "wait-container-app"],
+  // `publish-image` is core's verb; azure contributes the "acr" registry login backend.
 } as const;
 
 export const azureCapabilityPlugin: CapabilityPlugin = {
@@ -18,7 +23,17 @@ export const azureCapabilityPlugin: CapabilityPlugin = {
     return ownPackageVersion(import.meta.url);
   },
   capabilities(): Array<Capability<never, unknown>> {
-    return [armDeployCapability as Capability<never, unknown>];
+    return [
+      armDeployCapability,
+      waitForDeploymentCapability,
+      waitContainerAppCapability,
+    ] as unknown as Array<Capability<never, unknown>>;
+  },
+  registryBackends() {
+    return [acrRegistryBackend];
+  },
+  storageBackends() {
+    return [azureBlobStorageBackend];
   },
   families(): Record<string, readonly string[]> {
     return AZURE_VERB_FAMILIES;

package/src/components/index.ts

@@ -7,3 +7,7 @@ export {
   type ArmDeployOutput,
   type ArmDeployPlanArtifact,
 } from "./arm-deploy";
+export * from "./wait-azure";
+export * from "./builders";
+export { createAcrRegistryBackend, acrRegistryBackend } from "./acr-backend";
+export { createAzureBlobStorageBackend, azureBlobStorageBackend } from "./blob-backend";

package/src/components/publish-backend.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { CapabilityRegistry } from "@intentius/chant/components/capability";
+import { registerCapabilityPlugins } from "@intentius/chant/components/capability-plugin-loader";
+import { starterCapabilityPlugin } from "@intentius/chant/components/starter-plugin";
+import { createMockProcessRunner } from "@intentius/chant/components/verbs/__tests__/mock-process-runner";
+import { awsCapabilityPlugin } from "@intentius/chant-lexicon-aws/components";
+import { gcpCapabilityPlugin } from "@intentius/chant-lexicon-gcp/components";
+import { azureCapabilityPlugin } from "./capability-plugin";
+import { createAcrRegistryBackend } from "./acr-backend";
+
+describe("ACR registry backend (#3142)", () => {
+  it("matches azurecr hosts only", () => {
+    const b = createAcrRegistryBackend(createMockProcessRunner().runner);
+    expect(b.matches("myreg.azurecr.io")).toBe(true);
+    expect(b.matches("123.dkr.ecr.us-east-1.amazonaws.com")).toBe(false);
+  });
+
+  it("logs in with az acr login by registry name", async () => {
+    const mock = createMockProcessRunner();
+    await createAcrRegistryBackend(mock.runner).login("myreg.azurecr.io");
+    expect(mock.calls.map((c) => c.command)).toEqual(["az acr login --name 'myreg'"]);
+  });
+
+  it("refuses a host that is not an ACR", async () => {
+    await expect(createAcrRegistryBackend(createMockProcessRunner().runner).login("example.com")).rejects.toThrow(/not an Azure Container Registry/);
+  });
+});
+
+describe("a project declaring aws plus azure plus gcp (#3142, #3143)", () => {
+  it("loads without a duplicate-verb error and keeps one publish-image", () => {
+    const registry = registerCapabilityPlugins(new CapabilityRegistry(), [
+      starterCapabilityPlugin,
+      awsCapabilityPlugin,
+      azureCapabilityPlugin,
+      gcpCapabilityPlugin,
+    ]);
+    expect(registry.has("publish-image")).toBe(true);
+    expect(registry.has("arm-deploy")).toBe(true);
+    expect(registry.has("gcp-apply")).toBe(true);
+    expect(registry.has("cfn-deploy")).toBe(true);
+    const backends = [awsCapabilityPlugin, azureCapabilityPlugin, gcpCapabilityPlugin].flatMap((p) => p.registryBackends?.() ?? []);
+    expect(backends.map((b) => b.name).sort()).toEqual(["acr", "artifact-registry", "ecr"]);
+  });
+
+  it("no lexicon registers publish-image itself", () => {
+    for (const p of [awsCapabilityPlugin, azureCapabilityPlugin, gcpCapabilityPlugin]) {
+      expect(p.capabilities().map((c) => c.kind)).not.toContain("publish-image");
+    }
+  });
+});

package/src/components/storage-backend.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CapabilityRegistry } from "@intentius/chant/components/capability";
+import { registerCapabilityPlugins } from "@intentius/chant/components/capability-plugin-loader";
+import { starterCapabilityPlugin } from "@intentius/chant/components/starter-plugin";
+import { createPublishArtifactCapability } from "@intentius/chant/components/verbs/publish-artifact";
+import { createMockProcessRunner } from "@intentius/chant/components/verbs/__tests__/mock-process-runner";
+import { awsCapabilityPlugin } from "@intentius/chant-lexicon-aws/components";
+import { gcpCapabilityPlugin, createGcsStorageBackend } from "@intentius/chant-lexicon-gcp/components";
+import { azureCapabilityPlugin } from "./capability-plugin";
+import { createAzureBlobStorageBackend } from "./blob-backend";
+
+describe("Azure Blob storage backend (#4408)", () => {
+  it("matches blob hosts only", () => {
+    const b = createAzureBlobStorageBackend(createMockProcessRunner().runner);
+    expect(b.matches("https://acct.blob.core.windows.net/c/a.jar")).toBe(true);
+    expect(b.matches("s3://bucket/a.jar")).toBe(false);
+  });
+
+  it("uploads with az storage blob upload", async () => {
+    const mock = createMockProcessRunner();
+    await createAzureBlobStorageBackend(mock.runner).upload({ from: "/tmp/a.jar", to: "https://acct.blob.core.windows.net/cont/jars/a.jar" });
+    expect(mock.calls.map((c) => c.command)).toEqual([
+      "az storage blob upload --account-name 'acct' --container-name 'cont' --name 'jars/a.jar' --file '/tmp/a.jar' --overwrite --auth-mode login",
+    ]);
+  });
+
+  it("refuses a URI that is not a blob", async () => {
+    await expect(createAzureBlobStorageBackend(createMockProcessRunner().runner).upload({ from: "/a", to: "https://example.com/x" })).rejects.toThrow(/not a blob URI/);
+  });
+});
+
+describe("a project declaring aws plus azure plus gcp (#4408)", () => {
+  it("registers one publish-artifact and exposes three storage backends", () => {
+    const registry = registerCapabilityPlugins(new CapabilityRegistry(), [
+      starterCapabilityPlugin,
+      awsCapabilityPlugin,
+      azureCapabilityPlugin,
+      gcpCapabilityPlugin,
+    ]);
+    expect(registry.has("publish-artifact")).toBe(true);
+    const plugins = [awsCapabilityPlugin, azureCapabilityPlugin, gcpCapabilityPlugin];
+    expect(plugins.flatMap((p) => p.storageBackends?.() ?? []).map((b) => b.name).sort()).toEqual(["azure-blob", "gcs", "s3"]);
+    for (const p of plugins) expect(p.capabilities().map((c) => c.kind)).not.toContain("publish-artifact");
+  });
+
+  it("routes by destination URI to the right mocked backend", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-pa-"));
+    const file = join(dir, "a.jar");
+    writeFileSync(file, "J");
+    const az = createMockProcessRunner();
+    const gc = createMockProcessRunner();
+    const cap = createPublishArtifactCapability({
+      backends: [createAzureBlobStorageBackend(az.runner), createGcsStorageBackend(gc.runner)],
+    });
+    const ctx = { env: "dev", component: "c" } as never;
+    await cap.run(ctx, { from: file, to: "gs://bk/a.jar" });
+    await cap.run(ctx, { from: file, to: "https://acct.blob.core.windows.net/c/a.jar" });
+    expect(gc.calls.map((c) => c.command)).toEqual([`gcloud storage cp '${file}' 'gs://bk/a.jar'`]);
+    expect(az.calls).toHaveLength(1);
+  });
+});

package/src/components/wait-azure.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import type { AzHttp } from "../op/activities/az-apply";
+import { createWaitContainerAppCapability, createWaitForDeploymentCapability } from "./wait-azure";
+import { describeStackStatus } from "../describe-stack-status";
+
+const ctx = { env: "dev", component: "web" };
+const base = "/subscriptions/s/resourceGroups/web";
+
+/** A group whose resources change state after each poll: `states[i]` per resource, per round. */
+function fakeGroup(rounds: string[][], tags: Record<string, string> = { "chant-managed-by": "chant" }) {
+  let round = 0;
+  const http: AzHttp = async (_m, url) => {
+    const path = new URL(url).pathname;
+    if (path.endsWith("/resources")) {
+      const value = rounds[0]!.map((_, i) => ({ id: `${base}/providers/Microsoft.Storage/storageAccounts/a${i}`, name: `a${i}`, type: "Microsoft.Storage/storageAccounts", tags }));
+      return { status: 200, text: JSON.stringify({ value }) };
+    }
+    const i = Number(/a(\d+)$/.exec(path)![1]);
+    const state = rounds[Math.min(round, rounds.length - 1)]![i]!;
+    if (i === rounds[0]!.length - 1) round++;
+    return { status: 200, text: JSON.stringify({ name: `a${i}`, properties: { provisioningState: state } }) };
+  };
+  return http;
+}
+
+const fast = { sleep: async () => {}, now: () => 0 };
+
+describe("wait-for-deployment (#3142)", () => {
+  it("polls until every resource is terminal", async () => {
+    const cap = createWaitForDeploymentCapability({ ...fast, http: fakeGroup([["Creating", "Succeeded"], ["Succeeded", "Succeeded"]]) });
+    const out = await cap.run(ctx, { endpoint: "http://x" });
+    expect(out.resources.map((r) => r.state)).toEqual(["Succeeded", "Succeeded"]);
+  });
+
+  it("throws when a resource fails", async () => {
+    const cap = createWaitForDeploymentCapability({ ...fast, http: fakeGroup([["Failed"]]) });
+    await expect(cap.run(ctx, { endpoint: "http://x" })).rejects.toThrow(/ended Failed/);
+  });
+
+  it("times out while still provisioning", async () => {
+    let t = 0;
+    const cap = createWaitForDeploymentCapability({ sleep: async () => {}, now: () => (t += 1000), http: fakeGroup([["Creating"]]) });
+    await expect(cap.run(ctx, { endpoint: "http://x", timeoutMs: 1500 })).rejects.toThrow(/timed out.*Creating/);
+  });
+
+  it("declares no rollback", () => {
+    expect(createWaitForDeploymentCapability().rollback).toBeUndefined();
+  });
+});
+
+describe("wait-container-app (#3142)", () => {
+  const app = (props: Record<string, unknown>): AzHttp => async () => ({ status: 200, text: JSON.stringify({ properties: props }) });
+
+  it("returns once the latest revision is the latest ready one", async () => {
+    let n = 0;
+    const http: AzHttp = async () => {
+      const ready = ++n > 1;
+      return {
+        status: 200,
+        text: JSON.stringify({ properties: { provisioningState: "Succeeded", latestRevisionName: "app--2", latestReadyRevisionName: ready ? "app--2" : "app--1", configuration: { ingress: { fqdn: "app.example" } } } }),
+      };
+    };
+    const out = await createWaitContainerAppCapability({ ...fast, http }).run(ctx, { app: "app", endpoint: "http://x" });
+    expect(out).toEqual({ revision: "app--2", fqdn: "app.example" });
+    expect(n).toBe(2);
+  });
+
+  it("throws on a failed provisioning state", async () => {
+    const cap = createWaitContainerAppCapability({ ...fast, http: app({ provisioningState: "Failed" }) });
+    await expect(cap.run(ctx, { app: "app", endpoint: "http://x" })).rejects.toThrow(/ended Failed/);
+  });
+});
+
+describe("azure describeStackStatus (#3142)", () => {
+  it("is present and healthy when owned resources all succeeded", async () => {
+    const obs = await describeStackStatus({ environment: "dev", stack: "web" }, { endpoint: "http://x", http: fakeGroup([["Succeeded", "Succeeded"]]) });
+    expect(obs).toEqual({ stack: "web", present: true, status: "2/2 resources succeeded", healthy: true });
+  });
+
+  it("is unhealthy while one is still creating", async () => {
+    const obs = await describeStackStatus({ environment: "dev", stack: "web" }, { endpoint: "http://x", http: fakeGroup([["Succeeded", "Creating"]]) });
+    expect(obs).toMatchObject({ present: true, healthy: false });
+  });
+
+  it("is absent when nothing in the group is chant-owned", async () => {
+    const obs = await describeStackStatus({ environment: "dev", stack: "web" }, { endpoint: "http://x", http: fakeGroup([["Succeeded"]], {}) });
+    expect(obs).toEqual({ stack: "web", present: false });
+  });
+
+  it("is absent on a 404 group and indeterminate on a server error", async () => {
+    const notFound: AzHttp = async () => ({ status: 404, text: "{}" });
+    expect(await describeStackStatus({ environment: "dev", stack: "web" }, { endpoint: "http://x", http: notFound })).toEqual({ stack: "web", present: false });
+    const boom: AzHttp = async () => ({ status: 500, text: "{}" });
+    expect(await describeStackStatus({ environment: "dev", stack: "web" }, { endpoint: "http://x", http: boom })).toBeNull();
+  });
+});

package/src/components/wait-azure.ts

@@ -0,0 +1,163 @@
+/**
+ * wait / verify family, azure members (#3142): `wait-for-deployment` (every
+ * resource of a group reaches an ARM terminal provisioning state) and
+ * `wait-container-app` (a Container App serves its latest revision). Both
+ * poll ARM through the read client, so a test or floci-az swaps `http`. A wait
+ * is a read-only observation: neither declares a rollback.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { getResource, getResourceById, isNotFound, listResources, type AzureReadClientOptions } from "../api/read-client";
+import type { AzHttp } from "../op/activities/az-apply";
+
+const DEFAULT_INTERVAL_MS = 10_000;
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+/** ARM provisioning states that will not change without a new request. */
+const TERMINAL = new Set(["Succeeded", "Failed", "Canceled"]);
+
+export interface AzureWaitOptions {
+  http?: AzHttp;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+
+const realSleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+export interface TargetInput {
+  /** The resource group. Default: the component's name. */
+  resourceGroup?: string;
+  /** ARM endpoint. Default: `AZURE_ENDPOINT_URL`, else real Azure. */
+  endpoint?: string;
+  /** Subscription id. Default: `AZURE_SUBSCRIPTION_ID`, else floci-az's local subscription. */
+  subscriptionId?: string;
+  /** Poll interval in ms. Default: 10000. */
+  intervalMs?: number;
+  /** Overall timeout in ms. Default: 10 minutes. */
+  timeoutMs?: number;
+}
+
+function client(input: TargetInput, component: string, options: AzureWaitOptions): AzureReadClientOptions {
+  const endpoint = input.endpoint ?? process.env.AZURE_ENDPOINT_URL;
+  const subscriptionId = input.subscriptionId ?? process.env.AZURE_SUBSCRIPTION_ID;
+  return {
+    resourceGroup: input.resourceGroup ?? component,
+    ...(endpoint ? { endpoint } : {}),
+    ...(subscriptionId ? { subscriptionId } : {}),
+    ...(options.http ? { http: options.http } : {}),
+  };
+}
+
+function provisioningState(body: { properties?: Record<string, unknown> }): string | undefined {
+  const s = body.properties?.provisioningState;
+  return typeof s === "string" ? s : undefined;
+}
+
+// ── wait-for-deployment ──────────────────────────────────────────────────────
+
+export type WaitForDeploymentInput = TargetInput;
+
+export interface WaitForDeploymentOutput {
+  /** Resources of the group, each with the state it ended in. */
+  resources: Array<{ type: string; name: string; state: string }>;
+}
+
+/**
+ * Poll the group until no resource is still provisioning. Throws when one ends
+ * `Failed` or `Canceled`, or when the timeout passes first. A resource whose
+ * body carries no `provisioningState` (some types do not) counts as settled.
+ */
+export function createWaitForDeploymentCapability(
+  options: AzureWaitOptions = {},
+): Capability<WaitForDeploymentInput, WaitForDeploymentOutput> {
+  const sleep = options.sleep ?? realSleep;
+  const now = options.now ?? Date.now;
+  return {
+    kind: "wait-for-deployment",
+    async run(ctx, input) {
+      const read = client(input, ctx.component, options);
+      const interval = input.intervalMs ?? DEFAULT_INTERVAL_MS;
+      const deadline = now() + (input.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      while (true) {
+        const listed = await listResources(read);
+        const resources: WaitForDeploymentOutput["resources"] = [];
+        for (const item of listed) {
+          const body = item.id ? await getResourceById(read, item.id) : item;
+          resources.push({
+            type: String(item.type ?? ""),
+            name: String(item.name ?? ""),
+            state: provisioningState(body) ?? "Succeeded",
+          });
+        }
+        const bad = resources.find((r) => r.state === "Failed" || r.state === "Canceled");
+        if (bad) throw new Error(`wait-for-deployment "${read.resourceGroup}": ${bad.type}/${bad.name} ended ${bad.state}`);
+        if (resources.every((r) => TERMINAL.has(r.state))) return { resources };
+        if (now() > deadline) {
+          const pending = resources.filter((r) => !TERMINAL.has(r.state)).map((r) => `${r.name} (${r.state})`).join(", ");
+          throw new Error(`wait-for-deployment "${read.resourceGroup}" timed out; still provisioning: ${pending}`);
+        }
+        await sleep(interval);
+      }
+    },
+  };
+}
+
+export const waitForDeploymentCapability: Capability<WaitForDeploymentInput, WaitForDeploymentOutput> =
+  createWaitForDeploymentCapability();
+
+// ── wait-container-app ───────────────────────────────────────────────────────
+
+export interface WaitContainerAppInput extends TargetInput {
+  /** The Container App's name. */
+  app: string;
+}
+
+export interface WaitContainerAppOutput {
+  /** The revision serving traffic once the app is steady. */
+  revision: string;
+  /** The app's FQDN, when it has ingress. */
+  fqdn?: string;
+}
+
+/**
+ * Poll a Container App until provisioning succeeded and its latest revision is
+ * the latest ready one. A rollout that fails provisioning throws.
+ */
+export function createWaitContainerAppCapability(
+  options: AzureWaitOptions = {},
+): Capability<WaitContainerAppInput, WaitContainerAppOutput> {
+  const sleep = options.sleep ?? realSleep;
+  const now = options.now ?? Date.now;
+  return {
+    kind: "wait-container-app",
+    async run(ctx, input) {
+      const read = client(input, ctx.component, options);
+      const interval = input.intervalMs ?? DEFAULT_INTERVAL_MS;
+      const deadline = now() + (input.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      while (true) {
+        let state = "NotFound";
+        let ready = false;
+        let revision = "";
+        let fqdn: string | undefined;
+        try {
+          const body = await getResource(read, "Microsoft.App/containerApps", input.app);
+          const props = body.properties ?? {};
+          state = provisioningState(body) ?? "Unknown";
+          const latest = typeof props.latestRevisionName === "string" ? props.latestRevisionName : undefined;
+          const latestReady = typeof props.latestReadyRevisionName === "string" ? props.latestReadyRevisionName : undefined;
+          revision = latestReady ?? latest ?? "";
+          ready = state === "Succeeded" && (latest === undefined || latest === latestReady);
+          const ingress = (props.configuration as { ingress?: { fqdn?: unknown } } | undefined)?.ingress;
+          if (typeof ingress?.fqdn === "string") fqdn = ingress.fqdn;
+        } catch (err) {
+          if (!isNotFound(err)) throw err;
+        }
+        if (state === "Failed" || state === "Canceled") throw new Error(`wait-container-app "${input.app}" ended ${state}`);
+        if (ready) return { revision, ...(fqdn ? { fqdn } : {}) };
+        if (now() > deadline) throw new Error(`wait-container-app "${input.app}" timed out in state ${state}`);
+        await sleep(interval);
+      }
+    },
+  };
+}
+
+export const waitContainerAppCapability: Capability<WaitContainerAppInput, WaitContainerAppOutput> =
+  createWaitContainerAppCapability();

package/src/describe-stack-status.ts

@@ -0,0 +1,43 @@
+/**
+ * Deploy-unit status for Azure (#3142, the #1495 seam). An `arm-deploy` unit is
+ * its resource group. It is present when the group holds chant-owned
+ * resources (the ownership tags `arm-deploy` stamps), and healthy when every
+ * one of them reports a `Succeeded` provisioning state. A read that cannot
+ * happen (no credentials, ARM unreachable) is indeterminate (`null`), never a
+ * confident absence; a group ARM says does not exist is `present: false`.
+ */
+import type { StackStatusObservation } from "@intentius/chant/lexicon";
+import { getResourceById, isNotFound, listResources, type AzureReadClientOptions } from "./api/read-client";
+import { isChantOwned } from "./op/activities/az-apply";
+
+export async function describeStackStatus(
+  options: { environment: string; stack: string },
+  read: Partial<AzureReadClientOptions> = {},
+): Promise<StackStatusObservation | null> {
+  const client: AzureReadClientOptions = {
+    ...(process.env.AZURE_ENDPOINT_URL ? { endpoint: process.env.AZURE_ENDPOINT_URL } : {}),
+    ...(process.env.AZURE_SUBSCRIPTION_ID ? { subscriptionId: process.env.AZURE_SUBSCRIPTION_ID } : {}),
+    ...read,
+    resourceGroup: options.stack,
+  };
+  try {
+    const owned = (await listResources(client)).filter((r) => isChantOwned(r.tags));
+    if (owned.length === 0) return { stack: options.stack, present: false };
+    const states: string[] = [];
+    for (const item of owned) {
+      const body = item.id ? await getResourceById(client, item.id) : item;
+      const s = body.properties?.provisioningState;
+      states.push(typeof s === "string" ? s : "Succeeded");
+    }
+    const ok = states.filter((s) => s === "Succeeded").length;
+    return {
+      stack: options.stack,
+      present: true,
+      status: `${ok}/${states.length} resources succeeded`,
+      healthy: ok === states.length,
+    };
+  } catch (err) {
+    if (isNotFound(err)) return { stack: options.stack, present: false };
+    return null;
+  }
+}

package/src/plugin.ts

@@ -468,6 +468,12 @@ export const tags = defaultTags([
     await packageLexicon(opts);
   },
 
+  /** Deploy-unit status for `arm-deploy`'s resource group (#3142). */
+  async describeStackStatus(options) {
+    const { describeStackStatus } = await import("./describe-stack-status");
+    return describeStackStatus(options);
+  },
+
   async describeResources(options) {
     const { describeResources } = await import("./describe-resources");
     return describeResources(options);