@intentius/chant-lexicon-azure 0.124.39 → 0.124.41

package/dist/components/arm-deploy.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `arm-deploy`: the azure lexicon's apply step for components (#4273). It
+ * applies a built ARM template into one resource group through `azApply`
+ * (../op/activities/az-apply.ts), the same per-resource applier `ApplyOp`'s
+ * `arm` target and the floci-az lane use, so a component step, an Op and the
+ * emulator run share one code path.
+ *
+ * `plan` reads each template resource live with the read client
+ * (../api/read-client.ts) and compares it with the body `azApply` would PUT,
+ * normalized with the noise rules deep observation uses
+ * (../deep-observe.ts). A resource that is not there is a create, one whose
+ * claimed properties all match is a no-op, and one that differs is an update
+ * with each changed path before and after. With `prune: true`, each
+ * chant-owned resource in the group the template no longer declares is a
+ * delete, the set `pruneArmOrphans` would delete.
+ *
+ * ARM's PUT is a create-or-update with no preview, so the plan cannot ask
+ * Azure what would change the way `cfn-deploy` asks for a change set. What
+ * holds the apply to the approved plan is the digest: `run` plans again and
+ * applies only when it gets the approved one.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { type AzHttp, type AzNotPrunable } from "../op/activities/az-apply.js";
+export interface ArmDeployInput {
+    /** Path to the built ARM template (`deploymentTemplate.json`). */
+    template: string;
+    /** The resource group the template applies into. Default: the component's name. */
+    resourceGroup?: string;
+    /** Region for the group and for `resourceGroup().location`. Default: `eastus`. */
+    location?: 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;
+    /** Delete chant-owned resources of the group the template no longer declares. Default: false. */
+    prune?: boolean;
+}
+export interface ArmDeployOutput {
+    applied: Array<{
+        type: string;
+        name: string;
+    }>;
+    pruned: Array<{
+        type: string;
+        name: string;
+        deleted: boolean;
+    }>;
+    notPrunable: AzNotPrunable[];
+    /** The template's `outputs`, evaluated against the group once it applied. */
+    outputs: Record<string, unknown>;
+}
+/** What an `arm-deploy` plan hands `run` through `DeployContext.plans[resourceGroup]`. */
+export interface ArmDeployPlanArtifact {
+    kind: "arm-deploy-plan";
+    resourceGroup: string;
+    planDigest: string;
+}
+/**
+ * Thrown by `run` when planning again gives another digest than the approved
+ * plan: the group, the template or the endpoint moved since. Nothing is
+ * applied. `planMoved` is core's mark for a moved plan, so the command exits 3.
+ */
+export declare class ArmDeployPlanMovedError extends Error {
+    readonly resourceGroup: string;
+    readonly planned: string;
+    readonly now: string;
+    readonly planMoved = true;
+    constructor(resourceGroup: string, planned: string, now: string);
+}
+/**
+ * The `arm-deploy` capability over an injectable HTTP transport (the
+ * `AzHttp` seam `azApply` and the read client share). Tests pass a fake;
+ * the default is `fetch`. There is no rollback: like `gcp-apply`, it mutates
+ * with no undo, so COMP003 has a component acknowledge the gap.
+ */
+export declare function createArmDeployCapability(options?: {
+    http?: AzHttp;
+}): Capability<ArmDeployInput, ArmDeployOutput>;
+/** The default `arm-deploy` capability, over `fetch`. */
+export declare const armDeployCapability: Capability<ArmDeployInput, ArmDeployOutput>;
+//# sourceMappingURL=arm-deploy.d.ts.map

package/dist/components/arm-deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arm-deploy.d.ts","sourceRoot":"","sources":["../../src/components/arm-deploy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAiD,MAAM,wCAAwC,CAAC;AAQxH,OAAO,EAUL,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAOnC,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAChE,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,0FAA0F;AAC1F,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,iBAAiB,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAOD;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAG9B,aAAa,EAAE,MAAM;aACrB,OAAO,EAAE,MAAM;aACf,GAAG,EAAE,MAAM;IAJ7B,QAAQ,CAAC,SAAS,QAAQ;IAC1B,YACkB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EAO5B;CACF;AAkVD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,CAAC,cAAc,EAAE,eAAe,CAAC,CAyCtH;AAED,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,EAAE,UAAU,CAAC,cAAc,EAAE,eAAe,CAA+B,CAAC"}

package/dist/components/arm-deploy.js

@@ -0,0 +1,400 @@
+/**
+ * `arm-deploy`: the azure lexicon's apply step for components (#4273). It
+ * applies a built ARM template into one resource group through `azApply`
+ * (../op/activities/az-apply.ts), the same per-resource applier `ApplyOp`'s
+ * `arm` target and the floci-az lane use, so a component step, an Op and the
+ * emulator run share one code path.
+ *
+ * `plan` reads each template resource live with the read client
+ * (../api/read-client.ts) and compares it with the body `azApply` would PUT,
+ * normalized with the noise rules deep observation uses
+ * (../deep-observe.ts). A resource that is not there is a create, one whose
+ * claimed properties all match is a no-op, and one that differs is an update
+ * with each changed path before and after. With `prune: true`, each
+ * chant-owned resource in the group the template no longer declares is a
+ * delete, the set `pruneArmOrphans` would delete.
+ *
+ * ARM's PUT is a create-or-update with no preview, so the plan cannot ask
+ * Azure what would change the way `cfn-deploy` asks for a change set. What
+ * holds the apply to the approved plan is the digest: `run` plans again and
+ * applies only when it gets the approved one.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { MASKED, UNRESOLVED, deepPathSet, flattenDeepProperties, normalizeDeepProperties } from "@intentius/chant/deep-observation";
+import { diffDeep } from "@intentius/chant/lifecycle/deep-diff";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+import { AzureReadError, getResource, isNotFound, listResources } from "../api/read-client.js";
+import { azureDeepNormalizationHooks, buildLiveProperties } from "../deep-observe.js";
+import { classifyArmFailure } from "../describe-resources.js";
+import { armDependencies, azApply, evalArm, evalArmString, isChantOwned, orderArmResources, rememberDeployed, } from "../op/activities/az-apply.js";
+/** floci-az's local subscription, the applier's default too. */
+const DEFAULT_SUBSCRIPTION = "00000000-0000-0000-0000-000000000001";
+const DEFAULT_ENDPOINT = "https://management.azure.com";
+const DEFAULT_LOCATION = "eastus";
+function isArmDeployPlanArtifact(value) {
+    const v = value;
+    return v?.kind === "arm-deploy-plan" && typeof v.resourceGroup === "string" && typeof v.planDigest === "string";
+}
+/**
+ * Thrown by `run` when planning again gives another digest than the approved
+ * plan: the group, the template or the endpoint moved since. Nothing is
+ * applied. `planMoved` is core's mark for a moved plan, so the command exits 3.
+ */
+export class ArmDeployPlanMovedError extends Error {
+    constructor(resourceGroup, planned, now) {
+        super(`arm-deploy "${resourceGroup}": refusing to apply. Planning again gives ${now}, the approved plan was ${planned}; ` +
+            `the resource group or its template changed since. Plan it again.`);
+        this.resourceGroup = resourceGroup;
+        this.planned = planned;
+        this.now = now;
+        this.planMoved = true;
+        this.name = "ArmDeployPlanMovedError";
+    }
+}
+function targetOf(ctx, input) {
+    return {
+        resourceGroup: input.resourceGroup ?? ctx.component,
+        location: input.location ?? DEFAULT_LOCATION,
+        endpoint: (input.endpoint ?? process.env.AZURE_ENDPOINT_URL ?? DEFAULT_ENDPOINT).replace(/\/$/, ""),
+        subscriptionId: input.subscriptionId ?? process.env.AZURE_SUBSCRIPTION_ID ?? DEFAULT_SUBSCRIPTION,
+    };
+}
+function evalCtxOf(target, http) {
+    return {
+        subscriptionId: target.subscriptionId,
+        resourceGroup: target.resourceGroup,
+        location: target.location,
+        deployed: new Map(),
+        http,
+        base: target.endpoint,
+    };
+}
+function clientOf(target, http) {
+    return { endpoint: target.endpoint, subscriptionId: target.subscriptionId, resourceGroup: target.resourceGroup, http };
+}
+function readTemplate(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function templateDigest(path) {
+    try {
+        return `sha256:${createHash("sha256").update(readFileSync(path)).digest("hex")}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A 404 that means the resource is not there, as opposed to one that means the
+ * subscription is not: ARM answers `SubscriptionNotFound` with a 404 too, and
+ * planning every resource as a create on that answer would be wrong. A missing
+ * resource group is absence, since `azApply` creates the group first.
+ */
+function isAbsent(err) {
+    return isNotFound(err) && !(err instanceof AzureReadError && /^SubscriptionNotFound$/i.test(err.code ?? ""));
+}
+// ── The declared side ────────────────────────────────────────────────────────
+/** An expression that reads a resource's runtime state, which only an apply knows. */
+const RUNTIME_READ = /\b(reference|list[A-Za-z]*)\s*\(/;
+/**
+ * Evaluate one string the way `azApply` would, leaving an expression that
+ * reads runtime state (`reference()`, `listKeys()`) or uses a function the
+ * evaluator lacks as written. The noise rules read a bracket expression on
+ * the declared side as unresolved, so it is never compared, and the plan
+ * makes no `listKeys` call.
+ */
+async function evalStaticString(s, ctx) {
+    if (!(s.startsWith("[") && s.endsWith("]")) || s.startsWith("[["))
+        return evalArmString(s, ctx);
+    if (RUNTIME_READ.test(s))
+        return s;
+    try {
+        return await evalArmString(s, ctx);
+    }
+    catch {
+        return s;
+    }
+}
+async function evalStatic(value, ctx) {
+    if (typeof value === "string")
+        return evalStaticString(value, ctx);
+    if (Array.isArray(value))
+        return Promise.all(value.map((v) => evalStatic(v, ctx)));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[String(await evalStaticString(k, ctx))] = await evalStatic(v, ctx);
+        return out;
+    }
+    return value;
+}
+/**
+ * The fields `azApply` PUTs for a resource, in the flat shape deep
+ * observation reads a live resource into. The ownership tags `azApply` adds
+ * are left out: the noise rules drop them from the live side too.
+ */
+async function declaredTree(resource, name, ctx) {
+    const body = { name };
+    if (resource.location !== undefined)
+        body.location = (await evalStatic(resource.location, ctx));
+    for (const field of ["sku", "kind", "identity", "tags", "zones", "plan", "properties"]) {
+        if (resource[field] !== undefined)
+            body[field] = await evalStatic(resource[field], ctx);
+    }
+    return buildLiveProperties(body, name);
+}
+function attributeOf(path, before, after, hasBefore, hasAfter) {
+    if (before === MASKED || after === MASKED)
+        return { path, sensitive: true };
+    if (after === UNRESOLVED)
+        return { path, ...(hasBefore ? { before } : {}), unknown: true };
+    return { path, ...(hasBefore ? { before } : {}), ...(hasAfter ? { after } : {}) };
+}
+/** Read the group and compare it with the template. Pure apart from GETs. */
+async function readPlan(member, target, input, http) {
+    const template = readTemplate(input.template);
+    const resources = template.resources ?? [];
+    const ctx = evalCtxOf(target, http);
+    const client = clientOf(target, http);
+    const entries = [];
+    const holes = [];
+    const planned = [];
+    const base = (type, name) => ({
+        member,
+        lexicon: "azure",
+        planner: "chant",
+        address: `${type}/${name}`,
+        type,
+        name,
+    });
+    for (const resource of orderArmResources(resources)) {
+        const name = String(await evalStaticString(resource.name, ctx));
+        const address = `${resource.type}/${name}`;
+        if (name.startsWith("[")) {
+            holes.push({ address, type: resource.type, reason: "the resource's name reads runtime state; known only at apply" });
+            planned.push({ resource, name, action: "unread" });
+            continue;
+        }
+        const declaredRaw = await declaredTree(resource, name, ctx);
+        let live;
+        try {
+            live = (await getResource(client, resource.type, name, resource.apiVersion));
+        }
+        catch (err) {
+            if (!isAbsent(err)) {
+                const failure = classifyArmFailure(err);
+                holes.push({ address, type: resource.type, reason: `${failure.reason}: ${failure.detail}` });
+                planned.push({ resource, name, action: "unread" });
+                continue;
+            }
+        }
+        const opts = { entityType: resource.type, hooks: azureDeepNormalizationHooks };
+        if (!live) {
+            const declared = normalizeDeepProperties(declaredRaw, { ...opts, side: "declared" });
+            const attributes = [...flattenDeepProperties(declared, { ...opts, side: "declared" })]
+                .map(([path, value]) => attributeOf(path, undefined, value, false, true))
+                .sort((a, b) => a.path.localeCompare(b.path));
+            entries.push({ ...base(resource.type, name), action: "create", attributes });
+            planned.push({ resource, name, action: "create" });
+            continue;
+        }
+        rememberDeployed(ctx, resource.type, name, live);
+        const liveRaw = buildLiveProperties(live, name);
+        const declared = normalizeDeepProperties(declaredRaw, { ...opts, side: "declared", counterpartPaths: deepPathSet(liveRaw) });
+        const liveTree = normalizeDeepProperties(liveRaw, { ...opts, side: "live", counterpartPaths: deepPathSet(declaredRaw) });
+        const diff = diffDeep({
+            declared: { [address]: { type: resource.type, properties: declared } },
+            live: { resources: { [address]: { type: resource.type, properties: liveTree } }, unobserved: {} },
+            hooks: azureDeepNormalizationHooks,
+        });
+        // A masked value ARM does not return (a password) is write-only, not a change.
+        const changes = (diff.drifted[0]?.changes ?? []).filter((c) => !(c.kind === "absent" && c.declared === MASKED));
+        const id = typeof live.id === "string" ? { id: live.id } : {};
+        if (changes.length === 0) {
+            entries.push({ ...base(resource.type, name), ...id, action: "no-op", attributes: [] });
+            planned.push({ resource, name, action: "no-op" });
+            continue;
+        }
+        const attributes = changes
+            .map((c) => attributeOf(c.path, c.live, c.declared, c.kind === "changed", true))
+            .sort((a, b) => a.path.localeCompare(b.path));
+        entries.push({ ...base(resource.type, name), ...id, action: "update", disruption: "in-place", attributes });
+        planned.push({ resource, name, action: "update" });
+    }
+    if (input.prune) {
+        // The set `pruneArmOrphans` deletes: chant-owned, of any type, and not declared by (type, name).
+        const keep = new Set(planned.map((p) => `${p.resource.type}\0${p.name}`));
+        try {
+            for (const item of await listResources(client)) {
+                if (typeof item.type !== "string" || typeof item.name !== "string")
+                    continue;
+                if (!isChantOwned(item.tags))
+                    continue;
+                if (keep.has(`${item.type}\0${item.name}`))
+                    continue;
+                entries.push({
+                    ...base(item.type, item.name),
+                    ...(typeof item.id === "string" ? { id: item.id } : {}),
+                    action: "delete",
+                    disruption: "destroy",
+                    attributes: [],
+                });
+            }
+        }
+        catch (err) {
+            if (!isAbsent(err)) {
+                const failure = classifyArmFailure(err);
+                holes.push({ address: target.resourceGroup, type: "Microsoft.Resources/resourceGroups", reason: `prune not read: ${failure.reason}: ${failure.detail}` });
+            }
+        }
+    }
+    entries.sort((a, b) => a.address.localeCompare(b.address));
+    holes.sort((a, b) => a.address.localeCompare(b.address));
+    return { entries, holes, resources: planned, live: ctx, template };
+}
+function armPlanDigest(ctx, target, input, unresolved, plan) {
+    return computePlanDigest("arm-deploy-plan", {
+        env: ctx.env,
+        ...target,
+        template: input.template,
+        templateDigest: templateDigest(input.template),
+        prune: input.prune ?? false,
+        unresolved,
+        ...(plan ? { entries: plan.entries, holes: plan.holes } : {}),
+    });
+}
+/** The template's outputs evaluated against `ctx`, leaving out each one that evaluates to nothing. */
+async function evaluateOutputs(outputs, ctx, only) {
+    const known = {};
+    const unknown = [];
+    for (const [name, output] of Object.entries(outputs ?? {})) {
+        if (only && !only(name)) {
+            unknown.push(name);
+            continue;
+        }
+        let value;
+        try {
+            value = await evalArm(output?.value, ctx);
+        }
+        catch {
+            value = undefined;
+        }
+        if (value === undefined)
+            unknown.push(name);
+        else
+            known[name] = value;
+    }
+    return { known, unknown: unknown.sort() };
+}
+/**
+ * What the plan says of the template's outputs: an output whose value reads
+ * only resources the plan leaves as they are is known from the live read.
+ * Every other one is known only after apply.
+ */
+async function plannedOutputs(plan) {
+    const names = new Set(plan.resources.map((r) => r.resource.name));
+    const changing = new Set(plan.resources.filter((r) => r.action !== "no-op").map((r) => r.resource.name));
+    return evaluateOutputs(plan.template.outputs, plan.live, (name) => {
+        const value = plan.template.outputs?.[name]?.value;
+        const reads = armDependencies({ type: "", apiVersion: "", name: "", properties: value }, names);
+        return reads.every((r) => !changing.has(r));
+    });
+}
+/** Read every template resource live and evaluate the template's outputs against them. */
+async function liveOutputs(target, input, http) {
+    const template = readTemplate(input.template);
+    if (Object.keys(template.outputs ?? {}).length === 0)
+        return {};
+    const ctx = evalCtxOf(target, http);
+    const client = clientOf(target, http);
+    for (const resource of orderArmResources(template.resources ?? [])) {
+        const name = String(await evalStaticString(resource.name, ctx));
+        if (name.startsWith("["))
+            continue;
+        try {
+            rememberDeployed(ctx, resource.type, name, await getResource(client, resource.type, name, resource.apiVersion));
+        }
+        catch (err) {
+            if (!isAbsent(err))
+                throw err;
+        }
+    }
+    return (await evaluateOutputs(template.outputs, ctx)).known;
+}
+async function planArmDeploy(http, ctx, input) {
+    const target = targetOf(ctx, input);
+    const member = target.resourceGroup;
+    const unresolved = [...(ctx.unresolvedInputs ?? [])].sort();
+    const memberOf = (planDigest, holes) => ({
+        member,
+        lexicon: "azure",
+        planner: "chant",
+        status: "planned",
+        planDigest,
+        holes,
+    });
+    if (unresolved.length > 0) {
+        const planDigest = armPlanDigest(ctx, target, input, unresolved);
+        const hole = { address: member, type: "Microsoft.Resources/resourceGroups", reason: `inputs from ${unresolved.join(", ")}; re-checked on apply` };
+        return { member, planDigest, changeSet: { member: memberOf(planDigest, [hole]), entries: [] } };
+    }
+    const plan = await readPlan(member, target, input, http);
+    const planDigest = armPlanDigest(ctx, target, input, unresolved, plan);
+    const outputs = await plannedOutputs(plan);
+    // A plan with a hole hands `run` nothing to hold it to, as `cfn-deploy`'s does not.
+    const artifact = plan.holes.length === 0 ? { kind: "arm-deploy-plan", resourceGroup: member, planDigest } : undefined;
+    return {
+        member,
+        planDigest,
+        ...(artifact ? { artifact } : {}),
+        changeSet: { member: memberOf(planDigest, plan.holes), entries: plan.entries },
+        outputs,
+    };
+}
+/**
+ * The `arm-deploy` capability over an injectable HTTP transport (the
+ * `AzHttp` seam `azApply` and the read client share). Tests pass a fake;
+ * the default is `fetch`. There is no rollback: like `gcp-apply`, it mutates
+ * with no undo, so COMP003 has a component acknowledge the gap.
+ */
+export function createArmDeployCapability(options = {}) {
+    const http = options.http ?? (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() };
+    });
+    return {
+        kind: "arm-deploy",
+        rollbackPolicy: "needs-opt-out",
+        plan(ctx, input) {
+            return planArmDeploy(http, ctx, input);
+        },
+        outputs(ctx, input) {
+            return liveOutputs(targetOf(ctx, input), input, http);
+        },
+        async run(ctx, input) {
+            const target = targetOf(ctx, input);
+            const approved = ctx.plans?.[target.resourceGroup];
+            if (isArmDeployPlanArtifact(approved)) {
+                const now = await planArmDeploy(http, { env: ctx.env, component: ctx.component }, input);
+                if (now.planDigest !== approved.planDigest)
+                    throw new ArmDeployPlanMovedError(target.resourceGroup, approved.planDigest, now.planDigest);
+            }
+            const result = await azApply({
+                templatePath: input.template,
+                resourceGroup: target.resourceGroup,
+                location: target.location,
+                endpoint: target.endpoint,
+                subscriptionId: target.subscriptionId,
+                prune: input.prune ?? false,
+            }, undefined, http);
+            return { ...result, outputs: await liveOutputs(target, input, http) };
+        },
+    };
+}
+/** The default `arm-deploy` capability, over `fetch`. */
+export const armDeployCapability = createArmDeployCapability();

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

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

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

@@ -0,0 +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"}

package/dist/components/capability-plugin.js

@@ -0,0 +1,17 @@
+import { ownPackageVersion } from "@intentius/chant/components/capability-plugin";
+import { armDeployCapability } from "./arm-deploy.js";
+export const AZURE_VERB_FAMILIES = {
+    apply: ["arm-deploy"],
+};
+export const azureCapabilityPlugin = {
+    name: "azure",
+    get version() {
+        return ownPackageVersion(import.meta.url);
+    },
+    capabilities() {
+        return [armDeployCapability];
+    },
+    families() {
+        return AZURE_VERB_FAMILIES;
+    },
+};

package/dist/components/index.d.ts

@@ -0,0 +1,3 @@
+export { azureCapabilityPlugin, AZURE_VERB_FAMILIES } from "./capability-plugin.js";
+export { armDeployCapability, createArmDeployCapability, ArmDeployPlanMovedError, type ArmDeployInput, type ArmDeployOutput, type ArmDeployPlanArtifact, } from "./arm-deploy.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/components/index.js

@@ -0,0 +1,2 @@
+export { azureCapabilityPlugin, AZURE_VERB_FAMILIES } from "./capability-plugin.js";
+export { armDeployCapability, createArmDeployCapability, ArmDeployPlanMovedError, } from "./arm-deploy.js";

package/dist/composites/container-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container-app.d.ts","sourceRoot":"","sources":["../../src/composites/container-app.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,cAAc,EACd,MAAM,EACN,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,aAAa,EACd,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAC3D,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,cAAc,EAAE,YAAY,CAAC,OAAO,cAAc,CAAC,CAAC;IACpD,MAAM,EAAE,YAAY,CAAC,OAAO,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB;;;EA+BP,CAAC;AAE1B,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,WAAW,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,YAAY,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACxE,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,YAAY,CAAC,OAAO,qBAAqB,CAAC,CAAC;IACtD,QAAQ,EAAE,YAAY,CAAC,OAAO,eAAe,CAAC,CAAC;IAC/C,WAAW,EAAE,YAAY,CAAC,OAAO,mBAAmB,CAAC,CAAC;IACtD,YAAY,EAAE,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB;;;;;EAsEP,CAAC"}
+{"version":3,"file":"container-app.d.ts","sourceRoot":"","sources":["../../src/composites/container-app.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,cAAc,EACd,MAAM,EACN,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,aAAa,EACd,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAC3D,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,cAAc,EAAE,YAAY,CAAC,OAAO,cAAc,CAAC,CAAC;IACpD,MAAM,EAAE,YAAY,CAAC,OAAO,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB;;;EAyCP,CAAC;AAa1B,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,WAAW,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,YAAY,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACxE,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,YAAY,CAAC,OAAO,qBAAqB,CAAC,CAAC;IACtD,QAAQ,EAAE,YAAY,CAAC,OAAO,eAAe,CAAC,CAAC;IAC/C,WAAW,EAAE,YAAY,CAAC,OAAO,mBAAmB,CAAC,CAAC;IACtD,YAAY,EAAE,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB;;;;;EAsEP,CAAC"}

package/dist/composites/container-app.js

@@ -24,22 +24,39 @@ export const ContainerAppNetwork = Composite((props) => {
     const mergedTags = { "managed-by": "chant", ...tags };
     const vnetName = `${name}-vnet`;
     const delegations = [{ name: "apps", properties: { serviceName: "Microsoft.App/environments" } }];
+    const subnet = new Subnet(mergeDefaults({
+        name: `${vnetName}/apps`,
+        addressPrefix: subnetPrefix,
+        delegations,
+    }, defaults?.subnet), { apiVersion: "2023-05-01" });
     // The subnet is also listed inline, as VnetDefault does, so a later
-    // deployment of the VNet does not try to remove it.
+    // deployment of the VNet does not try to remove it. The inline entry is
+    // built from the Subnet resource's merged props, so `defaults.subnet`
+    // reaches both copies. The apps entry always comes first; a caller's
+    // `defaults.virtualNetwork.subnets` adds the other subnets after it, and
+    // an entry of theirs named "apps" is replaced by this one.
+    const { subnets: extraSubnets, ...vnetDefaults } = (defaults?.virtualNetwork ?? {});
     const virtualNetwork = new VirtualNetwork(mergeDefaults({
         name: vnetName,
         location,
         tags: mergedTags,
         addressSpace: { addressPrefixes: [addressSpace] },
-        subnets: [{ name: "apps", properties: { addressPrefix: subnetPrefix, delegations } }],
-    }, defaults?.virtualNetwork), { apiVersion: "2023-05-01" });
-    const subnet = new Subnet(mergeDefaults({
-        name: `${vnetName}/apps`,
-        addressPrefix: subnetPrefix,
-        delegations,
-    }, defaults?.subnet), { apiVersion: "2023-05-01" });
+        subnets: [
+            inlineSubnet("apps", subnetProps(subnet)),
+            ...(extraSubnets ?? []).filter((s) => s?.name !== "apps"),
+        ],
+    }, vnetDefaults), { apiVersion: "2023-05-01" });
     return { virtualNetwork, subnet };
 }, "ContainerAppNetwork");
+/** A Subnet resource's props, flat or under `properties`. */
+function subnetProps(subnet) {
+    return subnet.props;
+}
+/** The VNet's inline entry for a subnet, from that Subnet resource's props. */
+function inlineSubnet(name, props) {
+    const { name: _name, id: _id, properties, ...flat } = props;
+    return { name, properties: { ...flat, ...properties } };
+}
 /**
  * A Container Apps environment in a subnet, shipping logs to its own Log
  * Analytics workspace, with one app running as a user-assigned identity.

package/dist/deep-observe.d.ts

@@ -49,6 +49,36 @@
  */
 import { type AzHttp } from "./op/activities/az-apply.js";
 import type { DeepNormalizationHooks, DeepObservationResult } from "@intentius/chant/lexicon";
+/** The full `az resource show -o json` shape this reader reads (a superset of the thin path's `AzResourceShowResponse`). */
+export interface ArmResourceShowResponse {
+    id?: string;
+    name?: string;
+    type?: string;
+    location?: string;
+    kind?: string;
+    sku?: unknown;
+    identity?: unknown;
+    tags?: Record<string, string>;
+    zones?: string[];
+    plan?: unknown;
+    etag?: string;
+    systemData?: unknown;
+    properties?: Record<string, unknown>;
+}
+/**
+ * Reshape one `az resource show` response into chant's own flat declared
+ * vocabulary: the resource-level fields ARM returns as siblings of
+ * `properties`, plus every `properties.*` field spread onto that same top
+ * level (see the module doc). `id`/`type`/`etag`/`systemData` are envelope
+ * bookkeeping with no declared counterpart and are never read in at all.
+ *
+ * `queriedName` is the declared name the GET was addressed by. A child
+ * resource is declared as `vnet/subnet` while ARM answers with the leaf
+ * (`name: "subnet"`) — the same identity in two spellings, since the URL that
+ * returned 200 is the declared name. The leaf is folded back to the declared
+ * spelling; a name that is not the leaf of the query is kept as returned.
+ */
+export declare function buildLiveProperties(obj: ArmResourceShowResponse, queriedName?: string): Record<string, unknown>;
 /**
  * Server-populated wherever they appear — matched on the final path segment,
  * the same technique AWS's `AWS_READ_ONLY_NAMES` uses, because ARM repeats

package/dist/deep-observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,EAA4B,KAAK,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAGV,sBAAsB,EACtB,qBAAqB,EAGtB,MAAM,0BAA0B,CAAC;AA+DlC;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CASpD,CAAC;AAUH;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,MAAM,CAI1D,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI1E,CAAC;AA+DF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3D;AAyBD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBA2EzC,CAAC;AAIF,MAAM,WAAW,uBAAuB;IACtC,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAkEhC"}
+{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,EAA4B,KAAK,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAGV,sBAAsB,EACtB,qBAAqB,EAGtB,MAAM,0BAA0B,CAAC;AAQlC,4HAA4H;AAC5H,MAAM,WAAW,uBAAuB;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,uBAAuB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqB/G;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CASpD,CAAC;AAUH;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,MAAM,CAI1D,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI1E,CAAC;AA+DF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3D;AAyBD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBA2EzC,CAAC;AAIF,MAAM,WAAW,uBAAuB;IACtC,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAkEhC"}

package/dist/deep-observe.js

@@ -68,7 +68,7 @@ import { AZURE_TAG_OWNERSHIP_KEYS } from "./ownership.js";
  * returned 200 is the declared name. The leaf is folded back to the declared
  * spelling; a name that is not the leaf of the query is kept as returned.
  */
-function buildLiveProperties(obj, queriedName) {
+export function buildLiveProperties(obj, queriedName) {
     const out = {};
     if (obj.name !== undefined) {
         out.name =

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { defaultTags, type TagEntry, type DefaultTags } from "./default-tags.js"
 export { deploymentScope, isDeploymentScope, type DeploymentScope, type DeployScope } from "./deploy-scopes.js";
 export { azureSerializer } from "./serializer.js";
 export { azurePlugin } from "./plugin.js";
+export { azureCapabilityPlugin } from "./components/capability-plugin.js";
 export { Parameter } from "./parameter.js";
 export { observeResourcesDeepAzure, azureDeepNormalizationHooks, AZURE_READ_ONLY_NAMES, AZURE_SERVER_COMPUTED_NAMES, AZURE_SERVICE_DEFAULTS, } from "./deep-observe.js";
 export { ResourceId, ResourceIdIntrinsic, Reference, ReferenceIntrinsic, Concat, ConcatIntrinsic, ResourceGroup, ResourceGroupIntrinsic, Subscription, SubscriptionIntrinsic, UniqueString, UniqueStringIntrinsic, Format, FormatIntrinsic, If, IfIntrinsic, ListKeys, ListKeysIntrinsic, } from "./intrinsics.js";