@intentius/chant-lexicon-helm 0.41.3 → 0.41.5

package/dist/components/builders.d.ts

@@ -0,0 +1,3 @@
+import type { HelmUpgradeInput } from "./helm-upgrade.js";
+export declare const helmUpgrade: (input: HelmUpgradeInput) => 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,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,eAAO,MAAM,WAAW,yEAAyC,CAAC"}

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

@@ -0,0 +1,6 @@
+import { type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+export declare const HELM_VERB_FAMILIES: {
+    readonly apply: readonly ["helm-upgrade"];
+};
+export declare const helmCapabilityPlugin: 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":"AAWA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAGzG,eAAO,MAAM,kBAAkB;;CAErB,CAAC;AAEX,eAAO,MAAM,oBAAoB,EAAE,gBAWlC,CAAC"}

package/dist/components/helm-upgrade.d.ts

@@ -0,0 +1,41 @@
+import type { Capability } from "@intentius/chant/components/capability";
+export interface HelmUpgradeInput {
+    /**
+     * The release name — the deploy unit. `helm upgrade --install` converges
+     * it; `describeStackStatus` reads it back; `components status --live`
+     * reports it. Required: an unnamed release is invisible to every one of
+     * those.
+     */
+    release: string;
+    /** Chart reference: a local path, a `repo/chart` name, or an OCI ref. */
+    chart: string;
+    /** Target namespace. Omitted uses the kube context's default. */
+    namespace?: string;
+    /** Create the namespace if it does not exist (`--create-namespace`). */
+    createNamespace?: boolean;
+    /** Values files, passed as `-f` in order (later files win, Helm's rule). */
+    values?: string[];
+    /** Chart version constraint (`--version`). Omitted takes the latest. */
+    version?: string;
+    /** Wait for resources to become ready before returning (`--wait`). */
+    wait?: boolean;
+    /** Explicit kube context, overriding the environment's declared binding. */
+    context?: string;
+}
+/** What the upgrade did — Helm's own release facts, from `-o json`. */
+export interface HelmUpgradeOutcome {
+    release: string;
+    namespace?: string;
+    /** Helm's release revision after this upgrade (1 on first install). */
+    revision?: number;
+    /** Helm's native status, e.g. "deployed". */
+    status?: string;
+}
+/** Injectable command runner, so tests assert the exact argv without a cluster or a helm binary. */
+export type HelmRunner = (command: string) => Promise<{
+    stdout: string;
+}>;
+/** Factory with an injectable runner — the same seam `createKubectlApplyCapability` uses. */
+export declare function createHelmUpgradeCapability(run?: HelmRunner): Capability<HelmUpgradeInput, HelmUpgradeOutcome>;
+export declare const helmUpgradeCapability: Capability<HelmUpgradeInput, HelmUpgradeOutcome>;
+//# sourceMappingURL=helm-upgrade.d.ts.map

package/dist/components/helm-upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helm-upgrade.d.ts","sourceRoot":"","sources":["../../src/components/helm-upgrade.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,wCAAwC,CAAC;AAMxF,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,oGAAoG;AACpG,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AA8B1E,6FAA6F;AAC7F,wBAAgB,2BAA2B,CACzC,GAAG,GAAE,UAAsB,GAC1B,UAAU,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CA+BlD;AAED,eAAO,MAAM,qBAAqB,kDAAgC,CAAC"}

package/dist/components/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The helm lexicon's component/release surface: the `helm-upgrade`
+ * capability, its typed step-builder, and the `helmCapabilityPlugin` core
+ * loads when a project declares `lexicons: ["helm"]` (#1495 piece 4).
+ * Component authors import the builders from here
+ * (`@intentius/chant-lexicon-helm/components`), the way AWS and k8s verbs
+ * come from their lexicons' `/components` entries.
+ */
+export { helmCapabilityPlugin, HELM_VERB_FAMILIES } from "./capability-plugin.js";
+export * from "./builders.js";
+export { helmUpgradeCapability, createHelmUpgradeCapability, type HelmUpgradeInput, type HelmUpgradeOutcome, type HelmRunner, } from "./helm-upgrade.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;;;;;;;GAOG;AACH,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,10 @@
+import type { StackStatusObservation } from "@intentius/chant/lexicon";
+/** Injectable command runner, so tests drive every branch without helm or a cluster. */
+export type HelmRunner = (command: string) => Promise<{
+    stdout: string;
+}>;
+export declare function describeStackStatus(options: {
+    environment: string;
+    stack: string;
+}, run?: HelmRunner): 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":"AAuBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAMvE,wFAAwF;AACxF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAS1E,wBAAsB,mBAAmB,CACvC,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAC/C,GAAG,GAAE,UAAsB,GAC1B,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAyCxC"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { helmSerializer } from "./serializer.js";
 export { helmPlugin } from "./plugin.js";
+export { helmCapabilityPlugin, HELM_VERB_FAMILIES } from "./components/capability-plugin.js";
+export { helmUpgradeCapability, createHelmUpgradeCapability, type HelmUpgradeInput, type HelmUpgradeOutcome } from "./components/helm-upgrade.js";
 export { Chart, Values, ValuesOverride, HelmTest, HelmNotes, HelmHook, HelmDependency, HelmMaintainer, HelmCRD } from "./resources.js";
 export { HelmRender } from "./render.js";
 export type { HelmRenderProps } from "./render.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGpI,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAGhD,OAAO,EACL,OAAO,EACP,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,OAAO,EACP,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,WAAW,EACX,MAAM,EACN,KAAK,EACL,MAAM,EACN,GAAG,EACH,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,aAAa,EACb,cAAc,EACd,MAAM,EACN,EAAE,EACF,KAAK,EACL,IAAI,EACJ,SAAS,EACT,QAAQ,GACT,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvE,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAC1F,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGlG,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAKtC,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAC1F,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/I,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGpI,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAGhD,OAAO,EACL,OAAO,EACP,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,OAAO,EACP,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,WAAW,EACX,MAAM,EACN,KAAK,EACL,MAAM,EACN,GAAG,EACH,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,aAAa,EACb,cAAc,EACd,MAAM,EACN,EAAE,EACF,KAAK,EACL,IAAI,EACJ,SAAS,EACT,QAAQ,GACT,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvE,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAC1F,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGlG,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "fd02e1ca7a0b7258a39a086afd3ebca1dc0651bd328d93236908a79dfaf32a13",
+    "manifest.json": "0512e5bf71bbc2af393f201a22524ab869eb7e360e8bcf3aec24a3f39f381667",
     "meta.json": "14243c5730a07c6a6edc35ddd351438547d58df5cf345f2233a355b0c7611ccc",
     "types/index.d.ts": "5377696ca8698cd2999e4680feb8e8e4b54a7b49fb603a87b2f27356114d1794",
     "rules/chart-metadata.ts": "8f3377e893d5e2828460b7fe5924fca098334245a9a2fdb90f6b67e490eaf091",
@@ -34,5 +34,5 @@
     "skills/chant-helm-patterns.md": "9e79e6a46391da46709d8aa57e2825a7cd9eb981cd923f02ad60836c49b2561e",
     "skills/chant-helm-security.md": "bfc367eabceed2e84f1cf94501b407df78aeed963cec104f24a321d0962063c9"
   },
-  "composite": "0481181bf6f86f2b6c03bb25a221a93768e4dcb8767cc0fddb6bf4eb7d1ab6c2"
+  "composite": "43154d62e8f2d12a5798cb6fc107c2b5cf271e9f376195dbd9e76c5f5c22cad8"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "helm",
-  "version": "0.41.3",
+  "version": "0.41.5",
   "chantVersion": ">=0.1.0",
   "namespace": "Helm",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAY7F,eAAO,MAAM,UAAU,EAAE,aA6WxB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAY7F,eAAO,MAAM,UAAU,EAAE,aAqXxB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-helm",
-  "version": "0.41.3",
+  "version": "0.41.5",
   "description": "Helm chart lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -44,6 +44,11 @@
       "types": "./dist/detect.d.ts",
       "default": "./src/detect.ts"
     },
+    "./components": {
+      "development": "./src/components/index.ts",
+      "types": "./dist/components/index.d.ts",
+      "default": "./src/components/index.ts"
+    },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
@@ -76,7 +81,7 @@
     "@types/js-yaml": "^4.0.9"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.41.3",
+    "@intentius/chant": "^0.41.5",
     "typescript": "^5.9.3"
   }
 }

package/src/components/builders.ts

@@ -0,0 +1,11 @@
+/**
+ * Typed step-builders for the helm lexicon's verbs — the same ergonomic
+ * sugar the aws and k8s lexicons' `components/builders.ts` offer (#658),
+ * reusing the exported `step` projection from `@intentius/chant/components`.
+ * No `noRollback` admission here, unlike `kubectlApply`: `helm-upgrade`
+ * carries a native rollback, so COMP003 never asks for the opt-out.
+ */
+import { step } from "@intentius/chant/components";
+import type { HelmUpgradeInput } from "./helm-upgrade";
+
+export const helmUpgrade = step<HelmUpgradeInput>("helm-upgrade");

package/src/components/capability-plugin.ts

@@ -0,0 +1,30 @@
+/**
+ * `helmCapabilityPlugin` — the helm lexicon's capability plugin (#1495
+ * piece 4).
+ *
+ * One leaf: `helm-upgrade`, the idempotent create-or-converge verb a Helm
+ * release levels everything to. Contributed through core's `CapabilityPlugin`
+ * contract the same way aws contributes `cfn-deploy` and k8s contributes
+ * `kubectl-apply` — a project declaring `lexicons: ["helm"]` gets the verb
+ * registered automatically when it runs components.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { helmUpgradeCapability } from "./helm-upgrade";
+
+export const HELM_VERB_FAMILIES = {
+  apply: ["helm-upgrade"],
+} as const;
+
+export const helmCapabilityPlugin: CapabilityPlugin = {
+  name: "helm",
+  // The lexicon package's own version (#1505) — literals go stale every
+  // lockstep release.
+  version: ownPackageVersion(import.meta.url),
+  capabilities(): Array<Capability<never, unknown>> {
+    return [helmUpgradeCapability as Capability<never, unknown>];
+  },
+  families(): Record<string, readonly string[]> {
+    return HELM_VERB_FAMILIES;
+  },
+};

package/src/components/helm-upgrade.test.ts

@@ -0,0 +1,76 @@
+import { describe, test, expect } from "vitest";
+import { createHelmUpgradeCapability, helmUpgradeCapability } from "./helm-upgrade";
+import { helmCapabilityPlugin } from "./capability-plugin";
+import { isCapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { readFileSync } from "node:fs";
+import type { DeployContext } from "@intentius/chant/components/capability";
+
+const ctx: DeployContext = { env: "local", component: "test" };
+
+describe("helm-upgrade capability (#1495 piece 4)", () => {
+  test("the plugin satisfies the CapabilityPlugin contract and registers the verb", () => {
+    expect(isCapabilityPlugin(helmCapabilityPlugin)).toBe(true);
+    expect(helmCapabilityPlugin.capabilities().map((c) => c.kind)).toContain("helm-upgrade");
+  });
+
+  test("the plugin's version is the lexicon package's own, not a literal (#1505)", () => {
+    const { version } = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf-8"),
+    ) as { version: string };
+    expect(helmCapabilityPlugin.version).toBe(version);
+  });
+
+  test("run shells `helm upgrade --install` with the release, chart, and every declared flag", async () => {
+    let seen = "";
+    const cap = createHelmUpgradeCapability(async (cmd) => {
+      seen = cmd;
+      return { stdout: JSON.stringify({ name: "api", namespace: "prod", version: 3, info: { status: "deployed" } }) };
+    });
+
+    const out = await cap.run(ctx, {
+      release: "api",
+      chart: "./charts/api",
+      namespace: "prod",
+      createNamespace: true,
+      values: ["values.yaml", "values.prod.yaml"],
+      version: "1.2.3",
+      wait: true,
+      context: "k3d-test",
+    });
+
+    expect(seen).toBe(
+      "helm upgrade --install 'api' './charts/api' -o json -n 'prod' --create-namespace " +
+        "-f 'values.yaml' -f 'values.prod.yaml' --version '1.2.3' --wait --kube-context 'k3d-test'",
+    );
+    expect(out).toEqual({ release: "api", namespace: "prod", revision: 3, status: "deployed" });
+  });
+
+  test("non-JSON helm output still reports the release — the deploy already succeeded", async () => {
+    const cap = createHelmUpgradeCapability(async () => ({ stdout: "Release \"api\" has been upgraded.\n" }));
+    const out = await cap.run(ctx, { release: "api", chart: "repo/api", namespace: "prod" });
+    expect(out).toEqual({ release: "api", namespace: "prod" });
+  });
+
+  test("rollback shells `helm rollback` scoped to the release and namespace — the native compensation", async () => {
+    const commands: string[] = [];
+    const cap = createHelmUpgradeCapability(async (cmd) => {
+      commands.push(cmd);
+      return { stdout: "" };
+    });
+
+    await cap.rollback!(ctx, { release: "api", chart: "repo/api", namespace: "prod", context: "k3d-test" });
+    expect(commands).toEqual(["helm rollback 'api' -n 'prod' --kube-context 'k3d-test'"]);
+  });
+
+  test("no rollbackPolicy declared: a capability with a rollback method reads as native (COMP003)", () => {
+    expect(helmUpgradeCapability.rollback).toBeDefined();
+    expect(helmUpgradeCapability.rollbackPolicy).toBeUndefined();
+  });
+
+  test("a failing helm invocation rejects — a failed deploy must not report an outcome", async () => {
+    const cap = createHelmUpgradeCapability(async () => {
+      throw new Error("Error: UPGRADE FAILED: another operation is in progress");
+    });
+    await expect(cap.run(ctx, { release: "api", chart: "repo/api" })).rejects.toThrow(/UPGRADE FAILED/);
+  });
+});

package/src/components/helm-upgrade.ts

@@ -0,0 +1,133 @@
+/**
+ * `helm-upgrade` — the Helm release leaf for the component model
+ * (#1495 piece 4).
+ *
+ * The closest analogue of `cfn-deploy` anywhere in chant: a Helm release has
+ * a name, a presence, and a native status, and `helm upgrade --install` is
+ * the one idempotent verb that creates or converges it. `release` doubles as
+ * both the thing Helm manages and the deploy unit the status walk reads
+ * (core `components/deploy-units.ts` — `{ kind: "helm-upgrade", field:
+ * "release", lexicon: "helm" }` was registered in #1499, waiting for this
+ * capability to exist).
+ *
+ * Unlike `kubectl-apply`, rollback is native: Helm retains previous release
+ * revisions, and `helm rollback <release>` restores the last one. So this
+ * capability carries a real `rollback` method and COMP003 treats it as
+ * `"native"` — no opt-out reason required on the step.
+ *
+ * The cluster is selected the same way the k8s lexicon's reads select it
+ * (#1488): the environment's declared binding (`k8s.profiles.<env>.context`)
+ * is passed as `--kube-context` when present; ambient otherwise. Helm rides
+ * the same binding rather than inventing a parallel one — a Helm release
+ * lives on the same cluster the k8s half observes.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { Capability, DeployContext } from "@intentius/chant/components/capability";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { resolveClusterTarget } from "@intentius/chant/kubectl-context";
+
+const execAsync = promisify(exec);
+
+export interface HelmUpgradeInput {
+  /**
+   * The release name — the deploy unit. `helm upgrade --install` converges
+   * it; `describeStackStatus` reads it back; `components status --live`
+   * reports it. Required: an unnamed release is invisible to every one of
+   * those.
+   */
+  release: string;
+  /** Chart reference: a local path, a `repo/chart` name, or an OCI ref. */
+  chart: string;
+  /** Target namespace. Omitted uses the kube context's default. */
+  namespace?: string;
+  /** Create the namespace if it does not exist (`--create-namespace`). */
+  createNamespace?: boolean;
+  /** Values files, passed as `-f` in order (later files win, Helm's rule). */
+  values?: string[];
+  /** Chart version constraint (`--version`). Omitted takes the latest. */
+  version?: string;
+  /** Wait for resources to become ready before returning (`--wait`). */
+  wait?: boolean;
+  /** Explicit kube context, overriding the environment's declared binding. */
+  context?: string;
+}
+
+/** What the upgrade did — Helm's own release facts, from `-o json`. */
+export interface HelmUpgradeOutcome {
+  release: string;
+  namespace?: string;
+  /** Helm's release revision after this upgrade (1 on first install). */
+  revision?: number;
+  /** Helm's native status, e.g. "deployed". */
+  status?: string;
+}
+
+/** Injectable command runner, so tests assert the exact argv without a cluster or a helm binary. */
+export type HelmRunner = (command: string) => Promise<{ stdout: string }>;
+
+/** Shell-quote one argv element (paths and chart refs may carry spaces). */
+function q(arg: string): string {
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * The environment's kube context: the explicit input, else the declared
+ * binding (#1488 — used, never policed), else undefined (ambient).
+ */
+async function resolveContext(input: HelmUpgradeInput, env: string | undefined): Promise<string | undefined> {
+  if (input.context) return input.context;
+  if (!env) return undefined;
+  const { config } = await loadChantConfigUpward(process.cwd()).catch(() => ({ config: {} }));
+  const target = await resolveClusterTarget(config as Record<string, unknown>, env, "helm");
+  return target.context;
+}
+
+function upgradeCommand(input: HelmUpgradeInput, context: string | undefined): string {
+  const parts = ["helm", "upgrade", "--install", q(input.release), q(input.chart), "-o", "json"];
+  if (input.namespace) parts.push("-n", q(input.namespace));
+  if (input.createNamespace) parts.push("--create-namespace");
+  for (const f of input.values ?? []) parts.push("-f", q(f));
+  if (input.version) parts.push("--version", q(input.version));
+  if (input.wait) parts.push("--wait");
+  if (context) parts.push("--kube-context", q(context));
+  return parts.join(" ");
+}
+
+/** Factory with an injectable runner — the same seam `createKubectlApplyCapability` uses. */
+export function createHelmUpgradeCapability(
+  run: HelmRunner = execAsync,
+): Capability<HelmUpgradeInput, HelmUpgradeOutcome> {
+  return {
+    kind: "helm-upgrade",
+    async run(ctx: DeployContext, input: HelmUpgradeInput): Promise<HelmUpgradeOutcome> {
+      const context = await resolveContext(input, ctx.env);
+      const { stdout } = await run(upgradeCommand(input, context));
+      let parsed: { name?: string; namespace?: string; version?: number; info?: { status?: string } } = {};
+      try {
+        parsed = JSON.parse(stdout) as typeof parsed;
+      } catch {
+        // Helm printed something non-JSON (older helm, or a plugin banner) —
+        // the upgrade still succeeded (a failure rejects the exec), so report
+        // the release without the extras rather than failing a done deploy.
+      }
+      return {
+        release: input.release,
+        ...(parsed.namespace ?? input.namespace ? { namespace: parsed.namespace ?? input.namespace } : {}),
+        ...(typeof parsed.version === "number" ? { revision: parsed.version } : {}),
+        ...(parsed.info?.status ? { status: parsed.info.status } : {}),
+      };
+    },
+    // Native compensation: restore the previous retained revision. Helm's
+    // bare `rollback <release>` targets exactly that.
+    async rollback(ctx: DeployContext, input: HelmUpgradeInput): Promise<void> {
+      const context = await resolveContext(input, ctx.env);
+      const parts = ["helm", "rollback", q(input.release)];
+      if (input.namespace) parts.push("-n", q(input.namespace));
+      if (context) parts.push("--kube-context", q(context));
+      await run(parts.join(" "));
+    },
+  };
+}
+
+export const helmUpgradeCapability = createHelmUpgradeCapability();

package/src/components/index.ts

@@ -0,0 +1,17 @@
+/**
+ * The helm lexicon's component/release surface: the `helm-upgrade`
+ * capability, its typed step-builder, and the `helmCapabilityPlugin` core
+ * loads when a project declares `lexicons: ["helm"]` (#1495 piece 4).
+ * Component authors import the builders from here
+ * (`@intentius/chant-lexicon-helm/components`), the way AWS and k8s verbs
+ * come from their lexicons' `/components` entries.
+ */
+export { helmCapabilityPlugin, HELM_VERB_FAMILIES } from "./capability-plugin";
+export * from "./builders";
+export {
+  helmUpgradeCapability,
+  createHelmUpgradeCapability,
+  type HelmUpgradeInput,
+  type HelmUpgradeOutcome,
+  type HelmRunner,
+} from "./helm-upgrade";

package/src/describe-stack-status.test.ts

@@ -0,0 +1,62 @@
+import { describe, test, expect } from "vitest";
+import { describeStackStatus } from "./describe-stack-status";
+
+const list = (entries: unknown) => async () => ({ stdout: JSON.stringify(entries) });
+
+describe("helm describeStackStatus (#1495 piece 4)", () => {
+  test("a deployed release: present and healthy, with Helm's native status", async () => {
+    const obs = await describeStackStatus(
+      { environment: "local", stack: "api" },
+      list([{ name: "api", namespace: "prod", status: "deployed", revision: "3" }]),
+    );
+    expect(obs).toEqual({ stack: "api", present: true, status: "deployed", healthy: true });
+  });
+
+  test("a failed release: present, unhealthy, status carried verbatim", async () => {
+    const obs = await describeStackStatus(
+      { environment: "local", stack: "api" },
+      list([{ name: "api", namespace: "prod", status: "failed" }]),
+    );
+    expect(obs).toEqual({ stack: "api", present: true, status: "failed", healthy: false });
+  });
+
+  test("pending-upgrade is present but not healthy — deployed is the one success state", async () => {
+    const obs = await describeStackStatus(
+      { environment: "local", stack: "api" },
+      list([{ name: "api", status: "pending-upgrade" }]),
+    );
+    expect(obs).toMatchObject({ present: true, status: "pending-upgrade", healthy: false });
+  });
+
+  test("release not in the list: absent — the pre-first-install state", async () => {
+    const obs = await describeStackStatus(
+      { environment: "local", stack: "api" },
+      list([{ name: "other", status: "deployed" }]),
+    );
+    expect(obs).toEqual({ stack: "api", present: false });
+  });
+
+  test("a namespace-qualified unit only matches its own namespace", async () => {
+    const entries = [
+      { name: "api", namespace: "staging", status: "failed" },
+      { name: "api", namespace: "prod", status: "deployed" },
+    ];
+    const prod = await describeStackStatus({ environment: "local", stack: "prod/api" }, list(entries));
+    expect(prod).toMatchObject({ present: true, status: "deployed", healthy: true });
+
+    const gone = await describeStackStatus({ environment: "local", stack: "dev/api" }, list(entries));
+    expect(gone).toEqual({ stack: "dev/api", present: false });
+  });
+
+  test("helm missing or cluster unreachable: null — indeterminate, never a confident absence", async () => {
+    const obs = await describeStackStatus({ environment: "local", stack: "api" }, async () => {
+      throw new Error("helm: command not found");
+    });
+    expect(obs).toBeNull();
+  });
+
+  test("unparseable or non-array output: null", async () => {
+    expect(await describeStackStatus({ environment: "local", stack: "api" }, async () => ({ stdout: "WARNING: ..." }))).toBeNull();
+    expect(await describeStackStatus({ environment: "local", stack: "api" }, async () => ({ stdout: '{"not":"an array"}' }))).toBeNull();
+  });
+});

package/src/describe-stack-status.ts

@@ -0,0 +1,84 @@
+/**
+ * Deploy-unit status for Helm (#1495 piece 4).
+ *
+ * A Helm deploy unit *is* a release: `helm list` already reports its
+ * presence, revision, and native status, and that status lands on
+ * `StackStatusObservation` almost field-for-field — `deployed` is the one
+ * terminal success state, so `healthy` is exactly `status === "deployed"`.
+ * This reads back what `helm-upgrade` (the paired capability) writes, the
+ * same one-name-both-jobs pairing `cfn-deploy`/`kubectl-apply` have.
+ *
+ * Tri-state, matching the k8s observer's contract:
+ *  - release found        → `{ present: true, status, healthy }`
+ *  - release not in list  → `{ present: false }` (pre-first-install)
+ *  - helm missing, no cluster, exec failure, unparseable output → `null` —
+ *    "I cannot tell", never a confident absence.
+ *
+ * Cluster selection follows #1488: the environment's declared k8s binding
+ * (`k8s.profiles.<env>.context`) is passed as `--kube-context` when present;
+ * ambient otherwise. A Helm release lives on the same cluster the k8s half
+ * observes, so it rides the same binding.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { StackStatusObservation } from "@intentius/chant/lexicon";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { resolveClusterTarget } from "@intentius/chant/kubectl-context";
+
+const execAsync = promisify(exec);
+
+/** Injectable command runner, so tests drive every branch without helm or a cluster. */
+export type HelmRunner = (command: string) => Promise<{ stdout: string }>;
+
+interface HelmListEntry {
+  name?: string;
+  namespace?: string;
+  status?: string;
+  revision?: string;
+}
+
+export async function describeStackStatus(
+  options: { environment: string; stack: string },
+  run: HelmRunner = execAsync,
+): Promise<StackStatusObservation | null> {
+  // The unit is a release name, optionally namespace-qualified as
+  // "<namespace>/<name>" when the same release name exists in two namespaces.
+  const slash = options.stack.indexOf("/");
+  const wantNs = slash > 0 ? options.stack.slice(0, slash) : undefined;
+  const wantName = slash > 0 ? options.stack.slice(slash + 1) : options.stack;
+
+  let context: string | undefined;
+  try {
+    const { config } = await loadChantConfigUpward(process.cwd());
+    context = (await resolveClusterTarget(config as Record<string, unknown>, options.environment, "helm")).context;
+  } catch {
+    context = undefined;
+  }
+
+  let stdout: string;
+  try {
+    ({ stdout } = await run(`helm list -A -o json${context ? ` --kube-context '${context.replace(/'/g, "'\\''")}'` : ""}`));
+  } catch {
+    // Binary missing, no kubeconfig, cluster unreachable — indeterminate.
+    return null;
+  }
+
+  let entries: HelmListEntry[];
+  try {
+    entries = JSON.parse(stdout) as HelmListEntry[];
+    if (!Array.isArray(entries)) return null;
+  } catch {
+    return null;
+  }
+
+  const found = entries.find(
+    (e) => e.name === wantName && (wantNs === undefined || e.namespace === wantNs),
+  );
+  if (!found) return { stack: options.stack, present: false };
+
+  return {
+    stack: options.stack,
+    present: true,
+    ...(found.status ? { status: found.status, healthy: found.status === "deployed" } : {}),
+  };
+}

package/src/index.ts

@@ -4,6 +4,12 @@ export { helmSerializer } from "./serializer";
 // Plugin
 export { helmPlugin } from "./plugin";
 
+// #1495 piece 4 — the component surface. `helmCapabilityPlugin` exported from
+// the package entry is what `loadCapabilityPluginFromLexicon` scans for, the
+// same discovery the aws and k8s plugins ride.
+export { helmCapabilityPlugin, HELM_VERB_FAMILIES } from "./components/capability-plugin";
+export { helmUpgradeCapability, createHelmUpgradeCapability, type HelmUpgradeInput, type HelmUpgradeOutcome } from "./components/helm-upgrade";
+
 // Resources
 export { Chart, Values, ValuesOverride, HelmTest, HelmNotes, HelmHook, HelmDependency, HelmMaintainer, HelmCRD } from "./resources";
 

package/src/plugin.ts

@@ -382,4 +382,12 @@ export const service = new Service({
     const { listArtifacts } = await import("./list-artifacts");
     return listArtifacts(options);
   },
+
+  // #1495 piece 4 — the deploy-unit observer for helm-upgrade units: a
+  // release's presence and native status, read back by the same name the
+  // capability deploys under. Dynamic import mirrors listArtifacts.
+  async describeStackStatus(options) {
+    const { describeStackStatus } = await import("./describe-stack-status");
+    return describeStackStatus(options);
+  },
 };