@intentius/chant-lexicon-azure 0.124.31 → 0.124.32

package/dist/op/activities/az-apply.js

@@ -0,0 +1,563 @@
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { hasOwnershipMarker, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { AZURE_TAG_OWNERSHIP_KEYS } from "../../ownership.js";
+import { lookupApiVersion } from "../../serializer.js";
+import { compareApiDates } from "../../spec/api-versions.js";
+import { applyResult, } from "@intentius/chant/apply";
+// The floci-az default local subscription (from its ARM management-plane mock).
+const DEFAULT_SUBSCRIPTION = "00000000-0000-0000-0000-000000000001";
+const DEFAULT_ENDPOINT = "https://management.azure.com";
+const defaultHttp = async (method, url, body, signal) => {
+    const res = await fetch(url, {
+        method,
+        headers: body === undefined ? undefined : { "content-type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal,
+    });
+    return { status: res.status, text: await res.text() };
+};
+/** Evaluate an ARM expression string (`"[...]"`); a plain string is returned as-is. */
+export async function evalArmString(s, ctx) {
+    if (!(s.startsWith("[") && s.endsWith("]")))
+        return s;
+    if (s.startsWith("[["))
+        return s.slice(1); // escaped literal "["
+    return new ArmExpr(s.slice(1, -1), ctx).parse();
+}
+/** Recursively evaluate every string in a value against the ARM context. */
+export async function evalArm(value, ctx) {
+    if (typeof value === "string")
+        return evalArmString(value, ctx);
+    if (Array.isArray(value))
+        return Promise.all(value.map((v) => evalArm(v, ctx)));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = await evalArm(v, ctx);
+        return out;
+    }
+    return value;
+}
+/**
+ * Recursive-descent evaluator for the ARM function subset chant emits:
+ * `concat`, `uniqueString`, `resourceGroup()`, `subscription()`, `resourceId`,
+ * `reference` (runtime state of an applied resource), and `listKeys` (async key
+ * action), with `.prop` and `[index]` access.
+ */
+class ArmExpr {
+    constructor(src, ctx) {
+        this.src = src;
+        this.ctx = ctx;
+        this.i = 0;
+    }
+    async parse() {
+        return this.access(await this.atom());
+    }
+    async atom() {
+        this.ws();
+        return this.src[this.i] === "'" ? this.stringLiteral() : this.call();
+    }
+    /** Postfix `.prop` / `[index]` access. */
+    async access(v) {
+        for (;;) {
+            const c = this.peek();
+            if (c === ".") {
+                this.i++;
+                v = v?.[this.ident()];
+            }
+            else if (c === "[") {
+                this.i++;
+                v = v?.[this.indexNumber()];
+            }
+            else {
+                return v;
+            }
+        }
+    }
+    async call() {
+        const name = this.ident();
+        this.ws();
+        const args = [];
+        if (this.peek() === "(") {
+            this.i++;
+            this.ws();
+            if (this.peek() !== ")") {
+                args.push(await this.parse());
+                this.ws();
+                while (this.peek() === ",") {
+                    this.i++;
+                    args.push(await this.parse());
+                    this.ws();
+                }
+            }
+            if (this.peek() === ")")
+                this.i++;
+        }
+        return this.applyFn(name, args);
+    }
+    async applyFn(name, args) {
+        switch (name) {
+            case "concat":
+                return args.map(String).join("");
+            case "uniqueString":
+                return createHash("sha256").update(args.map(String).join("-")).digest("hex").slice(0, 13);
+            case "resourceGroup":
+                return { location: this.ctx.location, id: `/subscriptions/${this.ctx.subscriptionId}/resourceGroups/${this.ctx.resourceGroup}`, name: this.ctx.resourceGroup };
+            case "subscription":
+                return { subscriptionId: this.ctx.subscriptionId, id: `/subscriptions/${this.ctx.subscriptionId}` };
+            case "resourceId":
+                // resourceId('Microsoft.X/y', 'name'[, 'child']) → the resource-id path.
+                return `/subscriptions/${this.ctx.subscriptionId}/resourceGroups/${this.ctx.resourceGroup}/providers/${args.map(String).join("/")}`;
+            case "reference": {
+                // reference('name') → the runtime `properties` of an already-applied resource.
+                const dep = this.ctx.deployed.get(String(args[0]));
+                return dep?.properties ?? dep;
+            }
+            case "listKeys": {
+                // listKeys(resourceId, apiVersion) → POST the resource's key action.
+                const resId = String(args[0]);
+                const apiVersion = String(args[1] ?? "2023-01-01");
+                const res = await this.ctx.http("POST", `${this.ctx.base}${resId}/listKeys?api-version=${apiVersion}`, {}, this.ctx.signal);
+                try {
+                    return JSON.parse(res.text);
+                }
+                catch {
+                    return {};
+                }
+            }
+            default:
+                throw new Error(`unsupported ARM function: ${name}`);
+        }
+    }
+    stringLiteral() {
+        this.i++; // opening '
+        let out = "";
+        while (this.i < this.src.length && this.src[this.i] !== "'")
+            out += this.src[this.i++];
+        this.i++; // closing '
+        return out;
+    }
+    ident() {
+        this.ws();
+        let out = "";
+        while (this.i < this.src.length && /[A-Za-z0-9_]/.test(this.src[this.i]))
+            out += this.src[this.i++];
+        return out;
+    }
+    indexNumber() {
+        this.ws();
+        let n = "";
+        while (this.i < this.src.length && /[0-9]/.test(this.src[this.i]))
+            n += this.src[this.i++];
+        this.ws();
+        if (this.peek() === "]")
+            this.i++;
+        return parseInt(n, 10);
+    }
+    ws() {
+        while (this.i < this.src.length && /\s/.test(this.src[this.i]))
+            this.i++;
+    }
+    peek() {
+        this.ws();
+        return this.src[this.i];
+    }
+}
+// ── Dependency ordering ───────────────────────────────────────────────────────
+/** Resource names this resource references via `resourceId('type','name')` / `reference('name')`. Pure. */
+export function armDependencies(resource, names) {
+    const deps = new Set();
+    const scan = (v) => {
+        if (typeof v === "string") {
+            for (const m of v.matchAll(/resourceId\(\s*'[^']*'\s*,\s*'([^']*)'/g))
+                if (names.has(m[1]))
+                    deps.add(m[1]);
+            for (const m of v.matchAll(/reference\(\s*'([^']*)'/g))
+                if (names.has(m[1]))
+                    deps.add(m[1]);
+        }
+        else if (Array.isArray(v)) {
+            v.forEach(scan);
+        }
+        else if (v && typeof v === "object") {
+            Object.values(v).forEach(scan);
+        }
+    };
+    scan(resource);
+    deps.delete(resource.name);
+    return [...deps];
+}
+/**
+ * Topologically order ARM resources so a referenced resource is applied before
+ * the resource that references it. Names that are expressions are ordered as-is
+ * (they don't match a literal reference). Throws on a cycle. Pure.
+ */
+export function orderArmResources(resources) {
+    const byName = new Map();
+    for (const r of resources)
+        byName.set(r.name, r);
+    const names = new Set(resources.map((r) => r.name));
+    const ordered = [];
+    const done = new Set();
+    const active = new Set();
+    const visit = (r) => {
+        if (done.has(r))
+            return;
+        if (active.has(r))
+            throw new Error(`ARM reference cycle involving ${r.name}`);
+        active.add(r);
+        for (const dep of armDependencies(r, names)) {
+            const target = byName.get(dep);
+            if (target && target !== r)
+                visit(target);
+        }
+        active.delete(r);
+        done.add(r);
+        ordered.push(r);
+    };
+    for (const r of resources)
+        visit(r);
+    return ordered;
+}
+// ── URL + body + apply ────────────────────────────────────────────────────────
+/** The ARM resource-ID PUT URL for a resource (name expression evaluated). */
+export async function armResourceUrl(resource, ctx) {
+    const name = await evalArmString(resource.name, ctx);
+    return `${ctx.base}/subscriptions/${ctx.subscriptionId}/resourceGroups/${ctx.resourceGroup}/providers/${resource.type}/${name}?api-version=${resource.apiVersion}`;
+}
+/** The ARM resource PUT body (location/properties/sku/kind/tags), expressions evaluated. */
+export async function armResourceBody(resource, ctx) {
+    const body = {};
+    if (resource.location)
+        body.location = await evalArmString(resource.location, ctx);
+    if (resource.properties !== undefined)
+        body.properties = await evalArm(resource.properties, ctx);
+    if (resource.sku !== undefined)
+        body.sku = await evalArm(resource.sku, ctx);
+    if (resource.kind !== undefined)
+        body.kind = await evalArm(resource.kind, ctx);
+    if (resource.tags !== undefined)
+        body.tags = await evalArm(resource.tags, ctx);
+    return body;
+}
+/**
+ * The native Azure applier — read a built ARM template and PUT each resource
+ * directly to the ARM resource-CRUD API, in dependency order, resolving ARM
+ * expressions (including `reference()`/`listKeys()` against resources applied
+ * earlier this run). The Azure twin of `gcpApply`: it targets floci-az (which
+ * `az deployment` can't, floci-az having no deployments provider) or real Azure
+ * by endpoint override; the resource group is ensured first.
+ */
+export async function azApply(args, signal, http = defaultHttp) {
+    const base = (args.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
+    const ctx = {
+        subscriptionId: args.subscriptionId ?? DEFAULT_SUBSCRIPTION,
+        resourceGroup: args.resourceGroup,
+        location: args.location ?? "eastus",
+        deployed: new Map(),
+        http,
+        base,
+        signal,
+    };
+    // Ensure the resource group exists (ARM rejects resource PUTs without it).
+    await http("PUT", `${base}/subscriptions/${ctx.subscriptionId}/resourceGroups/${ctx.resourceGroup}?api-version=2021-04-01`, { location: ctx.location }, signal);
+    const template = JSON.parse(readFileSync(args.templatePath, "utf8"));
+    const resources = template.resources ?? [];
+    const applied = [];
+    for (const resource of orderArmResources(resources)) {
+        const name = String(await evalArmString(resource.name, ctx));
+        // Stamp chant ownership so a later prune can tell chant-managed resources
+        // apart from foreign ones in the same group.
+        const body = await armResourceBody(resource, ctx);
+        body.tags = { ...(body.tags ?? {}), ...chantOwnershipTags() };
+        const res = await http("PUT", await armResourceUrl(resource, ctx), body, signal);
+        if (res.status >= 300) {
+            throw new Error(`${resource.type} ${name} apply failed (${res.status}): ${res.text}`);
+        }
+        // Capture the applied resource so later reference()/dependents resolve.
+        try {
+            ctx.deployed.set(name, JSON.parse(res.text));
+        }
+        catch {
+            // non-JSON response — reference() to this resource resolves to undefined
+        }
+        console.log(`applied: ${resource.type}/${name} (${base})`);
+        applied.push({ type: resource.type, name });
+    }
+    const prune = args.prune
+        ? await pruneArmOrphans(resources, ctx, http, signal)
+        : { pruned: [], notPrunable: [] };
+    return { applied, pruned: prune.pruned, notPrunable: prune.notPrunable };
+}
+// ── Ownership + prune + delete ────────────────────────────────────────────────
+// chant stamps this tag on every resource it applies; prune only ever deletes
+// resources carrying it, so a foreign resource sharing the group is never
+// touched. Real Azure persists resource tags; note that floci-az currently drops
+// them, so owned-only prune only takes effect against real Azure (the delete
+// mechanics themselves work against either — see azDelete).
+/**
+ * The key this applier used before #1446, and still recognises.
+ *
+ * The lexicon declares its marker channel in `../../ownership.ts`
+ * (`chant-managed-by`) — the key the serializer stamps, the plugin registers as
+ * `ownershipChannel`, and `import/live-export.ts` filters on. This applier used
+ * a bare `managed-by` instead, so the two never agreed.
+ *
+ * That is not cosmetic. Both are ordinary ARM tag keys on the same surface, so
+ * nothing forced the difference — and it meant a resource carrying only the
+ * SERIALIZER's marker was invisible to this prune. Anything deployed by a path
+ * other than `azApply` reads as foreign and is never pruned, including
+ * everything `ApplyOp` deployed before #1448 routed it here from
+ * `az deployment --mode Complete`.
+ *
+ * (GCP has the same-looking split for a real reason: its serializer stamps a
+ * Config Connector object, where `app.kubernetes.io/managed-by` is a legal
+ * Kubernetes label, while `gcpApply` writes GCP REST labels, where it is not.
+ * Two surfaces, two key vocabularies. Azure has one surface.)
+ */
+export const LEGACY_OWNERSHIP_TAG_KEY = "managed-by";
+/**
+ * The ownership tags azApply stamps on every resource it applies.
+ *
+ * Stamps the declared channel's key. The legacy key goes on too, so a resource
+ * applied by this chant is still recognised by an older one mid-rollout; it is
+ * transitional and can be dropped once no deployed estate predates #1446.
+ *
+ * Only the managed-by marker, not stack/env: this applier has no
+ * {@link OwnershipMarker} to hand — the serializer stamps those from project
+ * config. Same shape the fly serializer uses when no ownership context is set.
+ */
+export function chantOwnershipTags() {
+    return {
+        [AZURE_TAG_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+        [LEGACY_OWNERSHIP_TAG_KEY]: OWNERSHIP_MANAGED_BY_VALUE,
+    };
+}
+/**
+ * Whether a resource's tags mark it chant-owned.
+ *
+ * Resolves through core's `hasOwnershipMarker` against the lexicon's declared
+ * channel (#1446), so this predicate and the serializer's stamp can no longer
+ * drift — the arrangement the fly lexicon already had.
+ *
+ * The legacy key is accepted as well, and the union is deliberate: it is
+ * strictly more than this predicate recognised before, so nothing that was
+ * prunable stops being prunable, and resources the serializer marked become
+ * prunable for the first time.
+ */
+export function isChantOwned(tags) {
+    if (hasOwnershipMarker(tags ?? undefined, AZURE_TAG_OWNERSHIP_KEYS))
+        return true;
+    return tags?.[LEGACY_OWNERSHIP_TAG_KEY] === OWNERSHIP_MANAGED_BY_VALUE;
+}
+/** List the resources in the group via the ARM resource-list endpoint. */
+export async function listGroupResources(ctx, http = defaultHttp, signal) {
+    const url = `${ctx.base}/subscriptions/${ctx.subscriptionId}/resourceGroups/${ctx.resourceGroup}/resources?api-version=2021-04-01`;
+    const res = await http("GET", url, undefined, signal);
+    if (res.status >= 300)
+        return [];
+    try {
+        return (JSON.parse(res.text).value ?? []).filter((r) => r?.type && r?.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** Idempotently delete one ARM resource by type/name/apiVersion. A 404 means it is already gone. */
+export async function deleteArmResource(type, name, apiVersion, ctx, http = defaultHttp, signal) {
+    const url = `${ctx.base}/subscriptions/${ctx.subscriptionId}/resourceGroups/${ctx.resourceGroup}/providers/${type}/${name}?api-version=${apiVersion}`;
+    const res = await http("DELETE", url, undefined, signal);
+    if (res.status === 404)
+        return { type, name, deleted: false };
+    if (res.status >= 300)
+        throw new Error(`${type} ${name} delete failed (${res.status}): ${res.text}`);
+    return { type, name, deleted: true };
+}
+/**
+ * Normalize an azApply/azDelete result into core's apply envelope (#1446).
+ *
+ * The lexicon keeps its own shape — ARM `type`, per-resource applied/pruned —
+ * and this projects it onto the shared tri-state so a caller can read any
+ * applier's result the same way.
+ */
+export function toApplyResult(result) {
+    const applied = (result.applied ?? []).map((a) => ({
+        kind: a.type,
+        name: a.name,
+        // ARM PUT is a create-or-update with no distinguishing response, so this
+        // applier cannot tell the two apart. `updated` is the honest verdict for a
+        // call that converged without claiming which it did.
+        action: "updated",
+    }));
+    const notAttempted = (result.notPrunable ?? []).map((n) => ({
+        kind: n.type,
+        name: n.name,
+        reason: "not-prunable",
+        detail: n.reason,
+    }));
+    const pruned = (result.pruned ?? result.deleted ?? []).map((p) => ({
+        kind: p.type,
+        name: p.name,
+        deleted: p.deleted,
+    }));
+    return applyResult(applied, pruned, notAttempted);
+}
+/** The ARM provider-metadata apiVersion (`GET /subscriptions/{sub}/providers/{ns}`). */
+const PROVIDER_METADATA_API_VERSION = "2021-04-01";
+/**
+ * Resolve an apiVersion for a live resource type from ARM's provider metadata:
+ * `GET /subscriptions/{sub}/providers/{namespace}?api-version=2021-04-01`
+ * returns `resourceTypes[].apiVersions[]`. Picks the newest stable version,
+ * falling back to the newest preview when no stable one exists. One call per
+ * namespace per prune run; the result is memoised in `cache` so a group with
+ * many orphans of one provider costs one round trip. Returns `undefined` when
+ * the endpoint is unavailable (floci-az does not implement it) or the type is
+ * not listed.
+ */
+export async function providerApiVersion(resourceType, ctx, http = defaultHttp, signal, cache = new Map()) {
+    const slash = resourceType.indexOf("/");
+    if (slash < 0)
+        return undefined;
+    const namespace = resourceType.slice(0, slash);
+    const typeName = resourceType.slice(slash + 1).toLowerCase();
+    let byType = cache.get(namespace.toLowerCase());
+    if (!byType) {
+        byType = new Map();
+        cache.set(namespace.toLowerCase(), byType);
+        const url = `${ctx.base}/subscriptions/${ctx.subscriptionId}/providers/${namespace}?api-version=${PROVIDER_METADATA_API_VERSION}`;
+        let res;
+        try {
+            res = await http("GET", url, undefined, signal);
+        }
+        catch {
+            return undefined;
+        }
+        if (res.status >= 300)
+            return undefined;
+        let parsed;
+        try {
+            parsed = JSON.parse(res.text);
+        }
+        catch {
+            return undefined;
+        }
+        for (const rt of parsed.resourceTypes ?? []) {
+            if (!rt?.resourceType || !Array.isArray(rt.apiVersions) || rt.apiVersions.length === 0)
+                continue;
+            const versions = rt.apiVersions.filter((v) => typeof v === "string");
+            const stable = versions.filter((v) => !v.endsWith("-preview"));
+            const pool = stable.length > 0 ? stable : versions;
+            if (pool.length === 0)
+                continue;
+            const newest = pool.reduce((a, b) => (compareApiDates(b, a) > 0 ? b : a));
+            byType.set(rt.resourceType.toLowerCase(), newest);
+        }
+    }
+    return byType.get(typeName);
+}
+/**
+ * Owned-only prune: delete every chant-owned live resource in the group whose
+ * (evaluated) name is not declared in the template. Foreign (non-chant)
+ * resources are never touched.
+ *
+ * ## Where the apiVersion comes from (#1457, #1472)
+ *
+ * `deleteArmResource` needs an `apiVersion`, and ARM's resource-group listing
+ * does not return one per resource. The template is the obvious source, but it
+ * only covers types it still declares: declare one storage account, apply,
+ * delete it from source, and the template has zero resources of that type.
+ * Keying the delete scope off the template alone made the last resource of a
+ * type a permanent orphan (#1457 made that a reported skip rather than a
+ * silent one).
+ *
+ * So the apiVersion is resolved in order:
+ *
+ * 1. the template, when it still declares the type;
+ * 2. the lexicon's pinned per-provider registry (`lookupApiVersion`, the same
+ *    registry the serializer stamps into the template) — deterministic, no
+ *    extra call, covers every type the lexicon can emit;
+ * 3. ARM's provider metadata (`providerApiVersion`) — covers a type the
+ *    lexicon has never heard of, at one extra call per namespace per run.
+ *
+ * Only when all three come up empty is the resource reported as
+ * `notPrunable: no-api-version`.
+ *
+ * This matters more since #1448, which routed `ApplyOp`'s `arm` target through
+ * `azApply` — before that, the composite reached `--mode Complete` and never
+ * came here at all.
+ */
+export async function pruneArmOrphans(desired, ctx, http = defaultHttp, signal) {
+    const byType = new Map();
+    for (const r of desired) {
+        const name = String(await evalArmString(r.name, ctx));
+        const entry = byType.get(r.type) ?? { keep: new Set(), apiVersion: r.apiVersion };
+        entry.keep.add(name);
+        byType.set(r.type, entry);
+    }
+    const providerCache = new Map();
+    const resolveApiVersion = async (type) => {
+        const fromTemplate = byType.get(type)?.apiVersion;
+        if (fromTemplate)
+            return fromTemplate;
+        let fromRegistry;
+        try {
+            fromRegistry = lookupApiVersion(type);
+        }
+        catch {
+            // A missing registry is the serializer's problem to report; prune still
+            // has the provider metadata to fall back on.
+        }
+        if (fromRegistry)
+            return fromRegistry;
+        return providerApiVersion(type, ctx, http, signal, providerCache);
+    };
+    const pruned = [];
+    const notPrunable = [];
+    for (const item of await listGroupResources(ctx, http, signal)) {
+        // Ownership first, so a foreign resource never reaches the report either —
+        // it is not an orphan chant failed to prune, it is simply not chant's.
+        if (!isChantOwned(item.tags))
+            continue;
+        if (byType.get(item.type)?.keep.has(item.name))
+            continue;
+        const apiVersion = await resolveApiVersion(item.type);
+        if (!apiVersion) {
+            console.log(`prune: ${item.type}/${item.name} is chant-owned and undeclared, but no apiVersion is ` +
+                `available for its type (not in the template, the lexicon registry, or ARM provider metadata) — not deleted`);
+            notPrunable.push({ type: item.type, name: item.name, reason: "no-api-version" });
+            continue;
+        }
+        const result = await deleteArmResource(item.type, item.name, apiVersion, ctx, http, signal);
+        console.log(`pruned: ${item.type}/${item.name} (${ctx.base})`);
+        pruned.push(result);
+    }
+    return { pruned, notPrunable };
+}
+/**
+ * The inverse of {@link azApply} — read a built ARM template and delete the
+ * resources it declares, in reverse dependency order (a referrer goes before the
+ * resource it references). Idempotent: already-absent resources are a no-op. The
+ * Azure twin of `gcpDelete`; `http` is injectable for tests.
+ */
+export async function azDelete(args, signal, http = defaultHttp) {
+    const base = (args.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
+    const ctx = {
+        subscriptionId: args.subscriptionId ?? DEFAULT_SUBSCRIPTION,
+        resourceGroup: args.resourceGroup,
+        location: args.location ?? "eastus",
+        deployed: new Map(),
+        http,
+        base,
+        signal,
+    };
+    const template = JSON.parse(readFileSync(args.templatePath, "utf8"));
+    const deleted = [];
+    for (const resource of orderArmResources(template.resources ?? []).reverse()) {
+        const name = String(await evalArmString(resource.name, ctx));
+        const result = await deleteArmResource(resource.type, name, resource.apiVersion, ctx, http, signal);
+        console.log(`${result.deleted ? "deleted" : "absent"}: ${resource.type}/${name} (${base})`);
+        deleted.push(result);
+    }
+    return { deleted };
+}

package/dist/op/activities/azure.js

@@ -0,0 +1,48 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+const DEFAULT_LOCATION = "eastus";
+/**
+ * Build the `az group create` command. `az group create` is idempotent — a group
+ * that already exists is returned unchanged — so no existence check is needed.
+ * Pure — exported for testing.
+ */
+export function azGroupEnsureCommand(resourceGroup, location) {
+    return `az group create --name ${resourceGroup} --location ${location} --output none`;
+}
+/** Build the `az group delete` command (non-blocking). Pure — exported for testing. */
+export function azGroupDeleteCommand(resourceGroup) {
+    return `az group delete --name ${resourceGroup} --yes --no-wait`;
+}
+/**
+ * Ensure an Azure resource group exists before an ARM deployment.
+ *
+ * `az deployment group create` (the `arm` target of `nativeApply`) fails if its
+ * resource group is absent — unlike CloudFormation, which creates its own stack.
+ * Run this before the apply. Uses fastIdempotent profile — 5m timeout.
+ *
+ * This targets real Azure (via the logged-in `az` context). Local emulation
+ * against floci-az awaits an upstream `Microsoft.Resources/deployments` provider
+ * (see #705); when that lands, an endpoint/custom-cloud override slots in here.
+ */
+export async function azGroupEnsure(args, signal) {
+    const location = args.location ?? DEFAULT_LOCATION;
+    const { stdout, stderr } = await execAsync(azGroupEnsureCommand(args.resourceGroup, location), { signal });
+    if (stdout)
+        console.log(stdout);
+    if (stderr)
+        console.error(stderr);
+}
+/**
+ * Delete an Azure resource group and everything in it (non-blocking). A no-op
+ * success when the group is already gone. Uses fastIdempotent profile — 5m
+ * timeout (`--no-wait` returns immediately).
+ */
+export async function azGroupDelete(args, signal) {
+    try {
+        await execAsync(azGroupDeleteCommand(args.resourceGroup), { signal });
+    }
+    catch {
+        // Group already absent — treat as success.
+    }
+}

package/dist/op/activities/floci-az.js

@@ -0,0 +1,37 @@
+import { emulatorLifecycle } from "@intentius/chant/op";
+// floci-az is a bespoke ARM fake (not LocalStack) — a plain 200 on its health
+// endpoint means ready. Shared lifecycle: emulatorLifecycle (#746).
+// Pinned rather than `:latest` (#1345): an image that moves underneath a
+// passing local suite is exactly the drift a pin exists to stop.
+export const FLOCI_AZ_SPEC = {
+    name: "chant-floci-az",
+    image: "floci/floci-az:0.10.0",
+    containerPort: 4577,
+    healthPath: "/_floci/health",
+    upstream: { repo: "floci-io/floci-az" },
+};
+/**
+ * The azure plugin's emulator capability (#1345).
+ *
+ * The spec below has existed since #746; what was missing was declaring it, so
+ * `chant emulator up --all` booted Floci and nothing else even though floci-az
+ * was one line away. `AZURE_ENDPOINT_URL` is the var azure's own
+ * `describe-resources.ts` and `deep-observe.ts` already read on every live
+ * call, which is also what makes `--live --env <local>` reach the emulator
+ * instead of real Azure.
+ */
+export const FLOCI_AZ_EMULATOR = {
+    spec: FLOCI_AZ_SPEC,
+    env: (endpoint) => ({ AZURE_ENDPOINT_URL: endpoint }),
+};
+const az = emulatorLifecycle(FLOCI_AZ_SPEC);
+export const flociAzExistsCommand = az.existsCommand;
+export const flociAzRmCommand = az.rmCommand;
+export const flociAzHealthUrl = az.healthUrl;
+/** The ARM endpoint URL (what `azApply`'s `endpoint` should point at). */
+export const flociAzEndpoint = az.endpoint;
+export const flociAzRunCommand = (args = {}) => az.runCommand(args);
+/** Boot a local floci-az (Azure emulator) in Docker and return its ARM endpoint. */
+export const flociAzUp = (args = {}, signal) => az.up(args, signal);
+/** Stop and remove the local floci-az container (no-op if already gone). */
+export const flociAzDown = (args = {}, signal) => az.down(args, signal);

package/dist/op/activities/index.js

@@ -0,0 +1,10 @@
+/**
+ * Azure Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `azure` lexicon. Contributes the resource-group
+ * lifecycle (`azGroupEnsure`/`azGroupDelete`) that an ARM `nativeApply` needs.
+ */
+export { azGroupEnsure, azGroupDelete, azGroupEnsureCommand, azGroupDeleteCommand } from "./azure.js";
+// floci-az (Azure emulator) lifecycle — the typed twin of aws's flociUp/Down, so
+// the trio's Azure op boots/tears down the emulator as a modeled step, not a shell.
+export { flociAzUp, flociAzDown, flociAzRunCommand, flociAzRmCommand, flociAzExistsCommand, flociAzHealthUrl, flociAzEndpoint, } from "./floci-az.js";
+export { azApply, azDelete, pruneArmOrphans, providerApiVersion, toApplyResult, deleteArmResource, listGroupResources, chantOwnershipTags, isChantOwned, evalArm, evalArmString, armResourceUrl, armResourceBody, armDependencies, orderArmResources, } from "./az-apply.js";