@intentius/chant 0.79.0 → 0.81.0

package/src/components/gate-plan.ts

@@ -0,0 +1,53 @@
+/**
+ * The plan a component gate approval is bound to (#2574).
+ *
+ * An Op gate binds the digest of the change set its Plan phase produced
+ * (#2300). A component has no Plan phase: what it will do is its composition,
+ * run against one environment. So the digest is taken over that, with the
+ * same `computePlanDigest` Op gates use.
+ *
+ * ## What it covers
+ *
+ * - The environment. An approval for staging never answers prod.
+ * - The composition as this run executes it: `deploy` and `rollback` phases
+ *   with every step's authored input. A promote and a rollback run a
+ *   transformed composition (`./promote.ts`), and a rollback's pins the
+ *   recorded digest into it, so each differs from a plain deploy's.
+ * - The release being deployed, when the caller names one. A promote checks
+ *   its publish output against a recorded digest that is not in the
+ *   composition, so it passes that digest here.
+ * - `vars`, the environment config the caller resolved ahead of the run.
+ *
+ * ## What it leaves out
+ *
+ * Anything decided during the run: outputs of earlier phases (a fresh build's
+ * digest differs on every build that is not reproducible, and binding it
+ * would make an approval unusable by the run that consumes it) and outputs of
+ * upstream components. The run id and the time are left out for the reasons
+ * `../lifecycle/plan-digest.ts` gives.
+ */
+
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DriverComponent } from "./driver";
+
+/** What a component gate's plan digest is taken over. */
+export interface ComponentGatePlan {
+  environment: string;
+  component: DriverComponent;
+  vars?: Record<string, unknown>;
+  /** The recorded digest a promote or rollback deploys, when the caller has one. */
+  release?: string;
+}
+
+/** The plan digest a component gate records and approves. */
+export function componentPlanDigest(plan: ComponentGatePlan): string {
+  const { component } = plan;
+  return computePlanDigest("component-deploy", {
+    environment: plan.environment,
+    component: component.name,
+    deploy: component.deploy,
+    rollback: component.rollback ?? null,
+    vars: plan.vars ?? null,
+    release: plan.release ?? null,
+  });
+}

package/src/components/pilots/README.md

@@ -13,7 +13,7 @@ The epic ([#551](https://github.com/INTENTIUS/chant/issues/551)) picked these th
 |---|---|---|---|---|---|---|
 | **Neo4j per-instance fan-out** | [`neo4j-fanout.pilot.ts`](./neo4j-fanout.pilot.ts) / [`neo4j-fanout.json`](../__fixtures__/neo4j-fanout.json) | no-build (`infra`, applies pre-built templates) | **fan-out** — one component composes 3 per-instance mini-compositions (`cfn-deploy` + `code-deploy` + `wait-cluster-healthy`), seed-first then rolling, gated at node 1 | simple apply (no `onReplace`/`stageGsi` — no sticky CFN concerns here) | none (self-contained cluster, no shared-stack imports) | **auto** — `code-deploy` (AWS CodeDeploy) rollback is native/automatic on failure, declared once inside the capability, never scripted per node |
 | **DynamoDB table** | [`dynamodb.pilot.ts`](./dynamodb.pilot.ts) / [`dynamodb-infra.json`](../__fixtures__/dynamodb-infra.json) | no-build (`infra`, applies an existing table template) | single (one `cfn-deploy`, no fan-out) | **sticky** — `onReplace: "block"` refuses a replacing changeset (data loss guard); `stageGsi: true` stages the GSI add→backfill→remove instead of an in-place replace | none | no rollback declared — a blocked replacement is not something to compensate, it is a stop |
-| **ALB/ECS target** | [`alb-ecs.pilot.ts`](./alb-ecs.pilot.ts) / [`alb-ecs-service.json`](../__fixtures__/alb-ecs-service.json) | **build** — `docker-build` → `publish-image` (promote by digest at deploy time) | single (one service, one `cfn-deploy` + `ecs-update-service`) | simple apply (no replacement-sensitive resource here) | **cross-stack** — imports `shared-alb`'s `ListenerArn`/`ClusterArn`/`Subnets` via `stackOutput()`, replacing the `describe-stacks \| jq` glue in [`examples/gitlab-aws-alb-services/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-services/src/pipeline.ts) | **no** (component-declared) — `ecs-update-service`/`cfn-deploy` have no native automatic rollback for an already-running service swap, so the component supplies an explicit `rollback` phase (`rollback-previous`) rather than relying on capability compensation |
+| **ALB/ECS target** | [`alb-ecs.pilot.ts`](./alb-ecs.pilot.ts) / [`alb-ecs-service.json`](../__fixtures__/alb-ecs-service.json) | **build** — `docker-build` → `publish-image` (promote by digest at deploy time) | single (one service, one `cfn-deploy` + `ecs-update-service`) | simple apply (no replacement-sensitive resource here) | **cross-stack** — imports `shared-alb`'s `ListenerArn`/`ClusterArn`/`Subnets` via `stackOutput()`, replacing the `describe-stacks \| jq` glue in [`examples/gitlab-aws-alb-services/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-services/src/pipeline.ts) | **no** — the in-run unwind calls `ecs-update-service`'s best-effort re-apply and `cfn-deploy`'s native rollback. The component declares no `rollback` phase (#2576), and an earlier release is restored with `chant components rollback` |
 
 Read together, the three cover every cell at least once: build only shows up for ALB/ECS, fan-out only for Neo4j, sticky-apply only for DynamoDB, cross-stack only for ALB/ECS, and both rollback styles (capability-native vs component-declared) appear once each.
 

package/src/components/pilots/alb-ecs.pilot.ts

@@ -1,7 +1,7 @@
 /**
  * Pilot: ALB/ECS target (#555, epic #551).
  *
- * Exercises the build + cross-stack + auto-rollback axes: `docker-build` →
+ * Exercises the build + cross-stack axes: `docker-build` →
  * `publish-image` (promote by digest, deploy-time) → `cfn-deploy` (importing
  * the shared ALB's listener/cluster/subnets as cross-stack outputs, resolved
  * by `chant graph --stacks` rather than a `describe-stacks | jq` pipeline
@@ -16,6 +16,12 @@
  * capabilities. `service` archetype: build → publish → apply → verify, the
  * fullest of the three archetypes.
  *
+ * It declares no component-level `rollback` phase (#2576). It used to declare
+ * one holding a `rollback-previous` step with only `service` and `cluster`,
+ * which the aws capability turned into an `aws ecs update-service` with no
+ * changes. Taking an environment back to an earlier recorded release is
+ * `chant components rollback` (#2531).
+ *
  * The JSON projection of this pilot is authoritative at
  * ../__fixtures__/alb-ecs-service.json (already schema-validated by
  * component-schema.test.ts) — this module is the real typed `Component`
@@ -54,10 +60,4 @@ export const searchService: Component = {
       { kind: "health-gate", path: "/healthz" },
     ]),
   ],
-  // No native `rollback` on ecs-update-service/cfn-deploy for an already-running
-  // service swap — the component declares an explicit compensation phase
-  // (auto/no-rollback axis: this is the "no automatic capability rollback,
-  // component supplies its own" side, contrasted with code-deploy's native
-  // automatic rollback in the Neo4j pilot).
-  rollback: [phase("Rollback", [{ kind: "rollback-previous", service: "search", cluster: "$env.cluster" }])],
 };

package/src/components/presets/ecs-fargate.ts

@@ -4,10 +4,16 @@
  * The named-composition builder for the ALB/ECS shape
  * (`../pilots/alb-ecs.pilot.ts`): `docker-build` -> `publish-image` ->
  * `cfn-deploy` (importing a shared ALB's cross-stack outputs) ->
- * `ecs-update-service` -> `wait-steady-state` + `health-gate`, with the same
- * component-declared `rollback-previous` compensation phase the pilot uses
- * (no native rollback for an already-running service swap — see
- * ../pilots/alb-ecs.pilot.ts's docstring).
+ * `ecs-update-service` -> `wait-steady-state` + `health-gate`.
+ *
+ * There is no component-level `rollback` phase (#2576). The preset used to
+ * declare one holding a `rollback-previous` step with only `service` and
+ * `cluster`. The aws capability behind that kind rolls a service back to the
+ * `taskDefinition` it is given, and with none given it ran `aws ecs
+ * update-service` with no changes, so the phase restored nothing. The
+ * in-run unwind still calls each executed step's own rollback, and taking an
+ * environment back to an earlier recorded release is `chant components
+ * rollback <env> --component <name>` (#2531).
  *
  * This is Level 2 reuse over Level 1 raw capabilities: a component that looks
  * like this composes `EcsFargateComponent({ ... })` directly; the odd case
@@ -98,6 +104,5 @@ export function EcsFargateComponent(config: EcsFargateComponentConfig): Componen
         { kind: "health-gate", path: config.healthPath },
       ]),
     ],
-    rollback: [phase("Rollback", [{ kind: "rollback-previous", service, cluster }])],
   };
 }